upstreamyard/discourse repository overview

⁠Discourse container image

Multi-arch (amd64, arm64), signed container images for Discourse⁠, the open-source community forum, built to run like any other app container: one process per container, configured by environment variables, with external PostgreSQL and Redis. Made for Kubernetes and Docker Compose.

Tags: latest, <year>.<month> (e.g. 2026.9), <version> (e.g. 2026.9.0, matching the Discourse release tags⁠). New Discourse releases are built automatically within 24 hours.

⁠At a glance

AI agents and coding assistants: read AGENTS.md⁠ for deployment rules, and llms.txt⁠ for an index of all docs.

⁠Quick start

curl -O https://raw.githubusercontent.com/upstreamyard/discourse/main/docker-compose.yml
cat > .env <<EOF
DISCOURSE_HOSTNAME=forum.example.com
DISCOURSE_SECRET_KEY_BASE=$(openssl rand -hex 64)
POSTGRES_PASSWORD=$(openssl rand -hex 16)
EOF
docker compose up -d
curl http://localhost:3000/srv/status

The first start runs the database migrations, which takes about half a minute on an empty database. Then create the first admin account:

docker compose exec discourse rake admin:create

Open http://localhost:3000 (or your hostname behind your proxy) and log in. Discourse sends sign-up and notification emails, so configure SMTP (below) before you invite anyone.

Or with plain docker run, against your own PostgreSQL and Redis:

docker run -d -p 3000:3000 \
  -e DISCOURSE_HOSTNAME=forum.example.com \
  -e DISCOURSE_DB_HOST=your-postgres -e DISCOURSE_DB_PASSWORD=... \
  -e DISCOURSE_REDIS_HOST=your-redis \
  -e DISCOURSE_SECRET_KEY_BASE=$(openssl rand -hex 64) \
  -v discourse_uploads:/var/www/discourse/public/uploads \
  -v discourse_backups:/var/www/discourse/public/backups \
  upstreamyard/discourse:latest

⁠Configuration

Discourse reads every setting from config/discourse_defaults.conf⁠ as an environment variable: DISCOURSE_ plus the setting name in upper case (db_host becomes DISCOURSE_DB_HOST). Forum settings (title, login options, categories, …) live in the database and are changed in the admin UI.

Settings of this image:

⁠Commands

The container's command selects the process:

rake, rails and discourse also work with docker exec and kubectl exec. The Docker HEALTHCHECK checks whichever process the container runs: /srv/status for web, the Redis heartbeat for sidekiq.

⁠Storage

Uploads and backups are written to the two volumes above. Mount them on persistent storage, and when you run more than one web container, use a shared (ReadWriteMany) volume for uploads or store uploads in S3-compatible object storage. Discourse's guide covers S3-compatible storage for uploads⁠; we haven't tested that path with this image yet.

⁠Plugins

The image contains the plugins that ship with Discourse (46 in 2026.9, including chat, Discourse AI, solved, reactions, templates and topic voting); enable them in the admin UI. Installing third-party plugins is not supported by this image yet.

⁠Kubernetes

The recommended way is the Helm chart (upstreamyard/helm-charts⁠):

helm repo add upstreamyard https://upstreamyard.github.io/helm-charts
helm install discourse upstreamyard/discourse --set discourse.hostname=forum.example.com

Running it yourself:

1. Run migrations once per release as a Job with the migrate command, and set MIGRATE_ON_BOOT=0 on the web pods.
2. Run web pods with UNICORN_SIDEKIQS=0 and a separate sidekiq Deployment, so web and background jobs scale independently.
3. Probe GET /srv/status on port 3000 for liveness, readiness and startup of web pods, and exec sidekiq-alive for Sidekiq pods (fails about 60 s after Sidekiq stops sending its heartbeat to Redis).
4. Run the regular migrations before the rollout with SKIP_POST_DEPLOYMENT_MIGRATIONS=1, and the post-deployment migrations (which remove old columns) after it.
5. Give the pods a shared uploads volume (or S3), and the same DISCOURSE_SECRET_KEY_BASE.

Stopping is graceful: on SIGTERM the web server finishes requests in flight before it exits. The container runs as non-root UID 10001 and is compatible with runAsNonRoot: true; it needs a writable root filesystem.

⁠Verifying images

Images are signed keylessly with cosign⁠ and include an SBOM and SLSA provenance:

cosign verify upstreamyard/discourse:latest \
  --certificate-identity-regexp '^https://github.com/upstreamyard/discourse/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

docker buildx imagetools inspect upstreamyard/discourse:latest --format '{{ json .SBOM }}'

⁠How it's built

.github/workflows/build.yml⁠ checks out the Discourse release tag and builds Dockerfile⁠ natively on amd64 and arm64 runners. Before publishing, scripts/smoke-test.sh⁠ starts each image against PostgreSQL with pgvector and Redis, creates an admin, loads the app's CSS and JavaScript, and creates a topic through the API. Everything is public and reproducible.

• Runtime libraries (Ruby, ImageMagick, libvips, oxipng, jemalloc, PostgreSQL client) come from Discourse's own discourse/base runtime image, at the tag Discourse's launcher uses.
• Frontend: Discourse's build downloads the prebuilt JavaScript bundle that Discourse publishes for each release, and the rest of the assets are precompiled in the image.
• Differences from Discourse's own image: one process per container instead of nginx, the app server and Sidekiq under runit; no launcher or rebuild step; runs as non-root; Sidekiq can run separately; graceful shutdown on SIGTERM; tini as PID 1 and a built-in HEALTHCHECK.

⁠Support

Issues with the image: open an issue here⁠. Questions about using Discourse: meta.discourse.org⁠.