Self-hosting configuration

The setup script writes docker/.env. Every value in this page lives there. Edit it and apply the change from the docker directory:

docker compose up -d --build

Values in .env are single-quoted, so $ and spaces are taken literally. A value cannot contain a single quote.

ContainersCopy Anchor Link

COMPOSE_PROFILES in .env turns the optional services on. https,rustfs is a domain with bundled storage; http is plain HTTP with an external bucket; add importer for GitHub imports. One of https or http is always on: the apps publish no ports of their own, and Caddy is what tells the API each visitor's address. Without it every visitor would share one sign-in rate limit.

AddressesCopy Anchor Link

Your own reverse proxyCopy Anchor Link

To terminate TLS in nginx, Traefik or a load balancer, set up the instance with its IP (the http profile), then set the three URL variables to your HTTPS origins and AUTH_COOKIE_DOMAIN to .<your domain>, and rebuild. Proxy:

• DOMAIN to port 3000
• api.DOMAIN to port 3001
• docs.DOMAIN to port 3003

Set X-Forwarded-For to the client address, as a single value, and do not limit the request body size on the API: a git push is one request.

EmailCopy Anchor Link

Set one of the two routes. The Docker setup requires one of them.

Running the API outside Docker with neither set, Ghost falls back to the local sendmail binary: SENDMAIL_PATH, or the first sendmail on PATH, /usr/sbin or /usr/lib. Windows has no built-in sendmail; a drop-in sendmail.exe on PATH is found the same way. With no route at all, email is dropped and verification has to stay off.

StorageCopy Anchor Link

The bucket is the source of truth for git data. Repository working copies in the API container are a cache rebuilt from it, so the API needs no volume. Ghost uses path-style addressing and region auto; any provider that accepts those works.

SecretsCopy Anchor Link

The setup script never replaces a secret that is already in .env.

An SSH host key by hand:

ssh-keygen -t ed25519 -N '' -f ghost_host_key
base64 -w0 ghost_host_key   # macOS: base64 -i ghost_host_key

Publish its fingerprint (ssh-keygen -lf ghost_host_key.pub) so people can check it on their first connection.

A commit signing key by hand:

gpg --batch --pinentry-mode loopback --passphrase '' --quick-gen-key Ghost ed25519 sign never
gpg --armor --export-secret-keys Ghost | base64 | tr -d '\n'

Ghost trusts only the key in COMMIT_SIGNING_KEY; old keys are not kept, so generate it once and back it up with the rest of .env. Commits GitHub signed, such as the merges in an imported repository, show as verified without any setup.

Git over SSHCopy Anchor Link

Port 22 usually belongs to the server's own SSH daemon. To use it for git, move the daemon first.

WebhooksCopy Anchor Link

See Receiving webhooks for the payload and signature format.

GitHub sign-in and importsCopy Anchor Link

With GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET set, the sign-in and sign-up forms offer Continue with GitHub. Someone new gets an account named after their GitHub login, with hyphens turned into underscores and a number added when the name is taken. Signing in with GitHub never takes over an existing account that shares the address: link GitHub from Settings → Security instead. The web app reads the client ID at build time, so rebuild web after setting it.

Imports are off unless all of these are set. With them, the new repository form offers Import from GitHub: people link their GitHub account, and the importer container copies the repository's branches, tags, releases, issues, pull requests and comments into Ghost. Imported issues and comments are authored by the ghost-importer account and credit the GitHub author in the text.

Create the OAuth app at github.com/settings/applications/new with:

• Homepage URL: WEB_APP_URL
• Authorization callback URL: <API_URL>/api/auth/callback/github

Generate IMPORTER_SECRET with openssl rand -hex 32, and add importer to COMPOSE_PROFILES. The setup script does both when you turn imports on.

The importer clones each repository to its container's temporary directory before pushing it, so the container needs disk for the largest repository you import. Release assets, Git LFS objects and line comments on pull requests are not imported.

TelemetryCopy Anchor Link

Off by default. Set OTEL_EXPORTER_OTLP_ENDPOINT to an OTLP HTTP endpoint, such as a Grafana Alloy or grafana/otel-lgtm container, to export traces and metrics from the API.

Running without the scriptCopy Anchor Link

Copy the variables in this page into docker/.env by hand, then:

cd docker
docker compose up -d --build

DATABASE_URL has to be postgres://ghost:<POSTGRES_PASSWORD>@postgres:5432/ghost, and ZOEKT_URL http://zoekt:6070.

TroubleshootingCopy Anchor Link

Logs for one service:

cd docker
docker compose logs -f api

Sign-in does nothing, or signs you out on reload. The web app and API are not sharing a cookie. With a domain, check AUTH_COOKIE_DOMAIN is .<DOMAIN> and both are served over HTTPS. In IP mode, open the web app on the same host name as API_URL, not localhost on one and an IP on the other.

Caddy cannot get a certificate. DNS for all three names has to reach the server, and ports 80 and 443 have to be open. docker compose logs caddy names the failing domain.

migrate exits with an error. The API does not start until migrations succeed. docker compose logs migrate shows the SQL error.

bucket fails with an external bucket. The key cannot see the bucket. Check the endpoint, the bucket name and the key's permissions.

SSH clone times out. The SSH port is closed in a firewall, or SSH_CLONE_HOST names a different host.

An import stays at "Importing" or fails with "The import could not be started". The API cannot reach the importer, or the two disagree on IMPORTER_SECRET. Check COMPOSE_PROFILES includes importer, then docker compose logs importer api. Failed imports retry on their own a few times; after that a repository admin can retry from the banner.

Linking GitHub fails with a redirect error. The OAuth app's callback URL has to be exactly <API_URL>/api/auth/callback/github.

Code search returns nothing. Repositories are indexed on push. Push once after the instance starts, then check docker compose logs zoekt.