From 2c9c97db74c34235d64d75b493813b0ed034808e Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Fri, 1 Nov 2024 18:51:53 -0500 Subject: [PATCH 1/2] Added Docker to Database Getting Started Signed-off-by: Andre Wanlin --- docs/getting-started/config/database.md | 31 +++++++++++++++++-------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/getting-started/config/database.md b/docs/getting-started/config/database.md index 0fbd66d5a3..a261b8e780 100644 --- a/docs/getting-started/config/database.md +++ b/docs/getting-started/config/database.md @@ -6,13 +6,13 @@ description: How to set up PostgreSQL for your Backstage instance. Audience: Admins -### Summary +## Summary This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Standalone Install](../index.md) guide. By the end of this tutorial, you will have a working PostgreSQL database hooked up to your Backstage install. -### Prerequisites +## Prerequisites This guide assumes a basic understanding of working on a Linux based operating system and have some experience with the terminal, specifically, these commands: `apt-get`, `psql`, `yarn`. @@ -23,7 +23,7 @@ This guide assumes a basic understanding of working on a Linux based operating s - If the database is not hosted on the same server as the Backstage app, the PostgreSQL port needs to be accessible (the default is `5432` or `5433`) -### 1. Install and configure PostgreSQL +## 1. Install and configure PostgreSQL :::tip Already configured your database? @@ -68,17 +68,27 @@ That's enough database administration to get started. Type `\q`, followed by pressing the enter key. Then again type `exit` and press enter. Next, you need to install and configure the client. -### 2. Configuring Backstage `pg` Client +### Docker Alternative -Go to the root directory of your freshly installed Backstage -App. Run the following to install the PostgreSQL client into your backend: +Alternatively you can run Postgres in a Docker container, this is great for local development or getting a Backstage POC up and running quickly, here's how: -```bash title="From your Backstage root directory" -yarn --cwd packages/backend add pg +First we need to pull down the container image, we'll use Postgres 17, check out the [Postgres Version Policy](../../overview/versioning-policy.md#postgresql-releases) to learn which versions as supported. + +```shell +docker pull postgres:17.0-bookworm ``` -Use your favorite editor to open `app-config.yaml` and add your PostgreSQL -configuration in the root directory of your Backstage app using the credentials from the previous steps. +Then we just need to start up the container. + +```shell +docker run -d --name postgres --restart=always -p 5432:5432 -e POSTGRES_PASSWORD= postgres:17.0-bookworm +``` + +This will run Postgres in the background for you, but remember to start it up again when you reboot your system. + +## 2. Configuring Backstage `pg` Client + +Use your favorite editor to open `app-config.yaml` and add your PostgreSQL configuration in the root directory of your Backstage app using the credentials from the previous steps. ```yaml title="app-config.yaml" backend: @@ -136,3 +146,4 @@ If you want to read more about the database configuration, here are some helpful - [Configuring Plugin Databases](../../tutorials/configuring-plugin-databases.md#privileges) - [Read more about Knex](http://knexjs.org/), the database wrapper that we use. +- [Install pgAdmin 4](https://www.pgadmin.org/), a helpful tool for querying your database. From 371d0ce5186ff9862a18bea61ceb1c9bbce83666 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Fri, 29 Nov 2024 11:39:43 -0600 Subject: [PATCH 2/2] Refactor based on feedback Signed-off-by: Andre Wanlin --- docs/getting-started/config/database.md | 63 +++++++++++++++++-------- 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/docs/getting-started/config/database.md b/docs/getting-started/config/database.md index a261b8e780..e6d1278b70 100644 --- a/docs/getting-started/config/database.md +++ b/docs/getting-started/config/database.md @@ -8,7 +8,7 @@ Audience: Admins ## Summary -This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Standalone Install](../index.md) guide. +This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Creating your Backstage App](../index.md) guide. By the end of this tutorial, you will have a working PostgreSQL database hooked up to your Backstage install. @@ -23,7 +23,7 @@ This guide assumes a basic understanding of working on a Linux based operating s - If the database is not hosted on the same server as the Backstage app, the PostgreSQL port needs to be accessible (the default is `5432` or `5433`) -## 1. Install and configure PostgreSQL +## 1. Install and Configure PostgreSQL :::tip Already configured your database? @@ -68,24 +68,6 @@ That's enough database administration to get started. Type `\q`, followed by pressing the enter key. Then again type `exit` and press enter. Next, you need to install and configure the client. -### Docker Alternative - -Alternatively you can run Postgres in a Docker container, this is great for local development or getting a Backstage POC up and running quickly, here's how: - -First we need to pull down the container image, we'll use Postgres 17, check out the [Postgres Version Policy](../../overview/versioning-policy.md#postgresql-releases) to learn which versions as supported. - -```shell -docker pull postgres:17.0-bookworm -``` - -Then we just need to start up the container. - -```shell -docker run -d --name postgres --restart=always -p 5432:5432 -e POSTGRES_PASSWORD= postgres:17.0-bookworm -``` - -This will run Postgres in the background for you, but remember to start it up again when you reboot your system. - ## 2. Configuring Backstage `pg` Client Use your favorite editor to open `app-config.yaml` and add your PostgreSQL configuration in the root directory of your Backstage app using the credentials from the previous steps. @@ -136,6 +118,47 @@ After the Backstage frontend launches, you should notice that nothing has change We've now made your data persist in your Backstage database. +## Alternatives + +You may not want to install Postgres locally, the following sections outline alternatives. + +### Docker + +You can run Postgres in a Docker container, this is great for local development or getting a Backstage POC up and running quickly, here's how: + +First we need to pull down the container image, we'll use Postgres 17, check out the [Postgres Version Policy](../../overview/versioning-policy.md#postgresql-releases) to learn which versions are supported. + +```shell +docker pull postgres:17.0-bookworm +``` + +Then we just need to start up the container. + +```shell +docker run -d --name postgres --restart=always -p 5432:5432 -e POSTGRES_PASSWORD= postgres:17.0-bookworm +``` + +This will run Postgres in the background for you, but remember to start it up again when you reboot your system. + +### Docker Compose + +Another way to run Postgres is to use Docker Compose, here's what that would look like: + +```yaml title="docker-compose.local.yaml" +version: '4' + +services: + postgres: + image: postgres:17.0-bookworm + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: + ports: + - 5432:5432 +``` + +Then you would just run `docker compose -f docker-compose.local.yaml up` to start Postgres. + ## Next Steps We recommend you read [Setting up authentication](./authentication.md) next.