Backstage Docker

An easy to configure, Docker Compose for Backstage. Includes support for

Lets Encrypt ssl cert for https support, including http -> http2 redirect
Basic Auth, for restricted access
Postgres database on persistent volume
An OpenSSH server to publish TechDocs to.

Extended Documentation

This Docker compose setup depends on a Backstage app as described in Bringing up Backstage. That post has an extended description leading to this hosting setup.

Requirements

Infrastructure

Runs on any machine supporting Docker, e.g., Digital Ocean, AWS EC2, bare metal, etc.
No reliance on cloud storage (for TechDocs)
Access to DNS A or CNAME record (for https)

Prerequisites

A Docker image of the Backstage application created via npx with a compatible app-config.production.yaml
A registry url for that Backstage app image, either to ghcr.io/rmorison/backstage-app:latest (from my build into ghcr.io) or to your own compatibly built instance
A .env file for the Docker compose, based on the sample.env
A server with Docker installed, with ports 80, 443, and 2222 open (we use 2222 for publishing TechDocs over scp)

TechDocs Publish SSH Keypair

You’ll need a public/private keypair to setup the TechDocs external publishing. I recommend you do not run the following on the server you’re hosting with, but on another, secure machine. It’s mostly important that you secure the private key, and not leave it lying around. Keeping it in your .ssh dir is ok. A password vault or manager is probably better, current events notwithstanding.

ssh-keygen -t rsa -b 4096 -N "" -C techdocs -f techdocs_rsa

Step by Step

Clone or copy this repo on your server

git clone https://github.com/rmorison/backstage-docker.git
cd backstage-docker

Create a .env file alongside the docker-compose.yml; start with the sample.env; see the Env Docs section below
```
cp sample.env .env
vi .env
    
```

Create a .htpasswd file with lines of output from the htpasswd program

sudo apt install --yes apache2-utils
htpasswd -bn backstage change-this-password >>.htpasswd

Point a domain to your server’s IP address via A or CNAME record (for Lets Encrypt certificate). That procedure is DNS provider specific, not covered here.
Bring up the docker cluster
```
docker compose up --build
    
```
Visit your instance at your BACKSTAGE_DOMAIN setting
- Import catalogs via the /catalog-import path
- Publish TechDocs via your external workflows: GH Action example

Env Docs

TRAEFIK_API_INSECURE: true/false to enable/disable traefik dashboard on port 8080; you could setup an ssh tunnel to access
BACKSTAGE_APP_TITLE: the app.title setting in the Backstage app config
BACKSTAGE_ORGANIZATION_NAME: the organization.name setting in the Backstage app config
BACKSTAGE_DOMAIN: DNS A or CNAME that points to this server’s IP address
BACKSTAGE_IMAGE: Docker image path of Backstage app, e.g., ghcr.io/rmorison/backstage-app:latest
TECHDOCS_DIR: mount point of published TechDocs tree in containers, e.g., /techdocs
TECHDOCS_SSH_PUBLIC_KEY: ssh public key (be sure to quote) for scp from a TechDocs publish workflow
- Tip: run ssh-keygen -t rsa -b 4096 -N "" -C techdocs -f techdocs_rsa, the contents of techdocs_rsa.pub goes here, the corresponding private key goes into the TECHDOCS_SSH_PRIVATE_KEY secret in the TechDocs publish workflow
- Warning: store the private key file securely
TECHDOCS_UID: set to the account UID running docker compose, e.g., 1000 on EC2; for owner of ./techdocs tree
TECHDOCS_GID: set to the account GID running docker compose, e.g., 1000 on EC2; for owner of ./techdocs tree
POSTGRES_HOST: needs to match postgres container in docker-compose.yml, e.g., db
POSTGRES_PORT: default 5432
POSTGRES_USER: Postgres backstage database user
POSTGRES_PASSWORD: Postgres backstage database user password
LETSENCRYPT_ADMIN_EMAIL: Your admin email for Lets Encrypt cert

rmorison / backstage-docker