Docker Compose

The postqueen-docker-compose repository is the supported way to run PostQueen. Its docker-compose.yaml starts PostQueen with PostgreSQL, Redis and Temporal. This page is the reference for that file. For a guided install, follow Try it locally or Deploy to a server.

What the stack starts

docker compose up -d starts eight containers:

Service	What it is	Reachable at
`postqueen`	The PostQueen image: web app, API and workers behind nginx	`localhost:4007` on the host
`postqueen-postgres`	PostgreSQL 17, all PostQueen data	The Docker network only
`postqueen-redis`	Redis 7.2, caches and rate-limit counters	The Docker network only
`temporal`	The Temporal server that runs the schedule	`127.0.0.1:7233`
`temporal-postgresql`	Temporal’s own database	The Docker network only
`temporal-elasticsearch`	Temporal’s search index	The Docker network only
`temporal-ui`	Temporal’s web UI	`127.0.0.1:8080`
`temporal-admin-tools`	The Temporal command-line tools, for debugging	Not published

A ninth service, spotlight, starts only with docker compose --profile debug up -d: a local Sentry Spotlight viewer for development. postqueen waits until PostgreSQL, Redis and Temporal report healthy, and has a health check of its own. On a server, change its port line to "127.0.0.1:4007:5000", because Docker publishes ports past a host firewall: see Deploy to a server.

Where settings live

Every setting is an environment variable on the postqueen service, and the place to put them is a .env file next to docker-compose.yaml. The Compose file reads it in two ways:

env_file passes every line of .env into the container. The file is optional (required: false), which needs Compose v2.24 or newer. This is how variables the YAML does not list, such as NOT_SECURED or NEYNAR_APP_FID, reach PostQueen.
${VAR:-default} fills the variables the YAML does list from the same .env, and falls back to the default after :- when the file does not set them.

.env

JWT_SECRET=a-long-random-string
ENCRYPTION_KEY=another-long-random-string
FRONTEND_URL=https://postqueen.example.com
LINKEDIN_CLIENT_ID=your-client-id

The syntax is KEY=value, one per line. Configuration reference lists every variable.

A literal value in environment: beats .env. Compose gives the environment: block priority over env_file for the same key. The ${VAR:-default} form is what lets .env win, so keep that form if you edit the YAML: replacing "${FRONTEND_URL:-http://localhost:4007}" with a fixed string means .env no longer changes it.

The postqueen-config volume is not a settings folder. The Compose file mounts it at /config, but nothing in the image reads files there. Use .env.

Apply a change

Recreate the app container so it reads the new values. A plain docker restart or docker compose restart keeps the old container and its old environment. In the folder that holds docker-compose.yaml, recreate only the postqueen service:

docker compose up -d --no-deps --force-recreate postqueen

The database, Redis and Temporal keep running. Avoid docker compose down for a settings change: on a host that runs other Compose services in the same project, it stops them too. On Kubernetes, see Kubernetes with Helm. Then check the backend’s own verdict on the settings. It logs each problem at startup and keeps running regardless:

docker compose logs postqueen | grep -i "configuration issue"

No output means the required settings passed. A line such as FRONTEND_URL should not end with / names what to fix.

Settings most installs change

Variable	Shipped default	Set it to
`JWT_SECRET`	A placeholder sentence	A long random string, `openssl rand -hex 32`. Set once and keep.
`ENCRYPTION_KEY`	Empty, so `JWT_SECRET` is used	A second long random string, set before there is data
`MAIN_URL`, `FRONTEND_URL`	`http://localhost:4007`	Your public `https://` address
`NEXT_PUBLIC_BACKEND_URL`	`http://localhost:4007/api`	The same address with `/api`
`NOT_SECURED`	Not set	`true` for a local try over HTTP only
`DISABLE_REGISTRATION`	`false`	`true` once the people who need accounts have them
`STORAGE_PROVIDER`	`local`	`cloudflare` for Cloudflare R2
`EMAIL_PROVIDER`	Not set, so no mail	`resend` or `nodemailer`: see Email

Leave these as they ship:

BACKEND_INTERNAL_URL, http://localhost:3000: the web app’s path to the API inside the container.
DATABASE_URL, REDIS_URL and TEMPORAL_ADDRESS: they point at the bundled services by name. Change them only to use your own.
RUN_CRON, true: it starts the recurring workflows, such as the sweep that picks up posts that failed to schedule. Any value turns it on, false included, and the YAML falls back to true when .env leaves it out. To turn it off, delete its line from docker-compose.yaml.
UPLOAD_DIRECTORY, /uploads, and NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY, uploads: the image’s nginx serves exactly that folder.

Pin the image

The file ships with image: ghcr.io/gkhankinay/postqueen-app:latest, which moves with every release. On a real install, pin a release tag:

image: ghcr.io/gkhankinay/postqueen-app:vX.Y.Z

Tags carry a v and are listed on the app’s tags and the image package. The GitHub Releases page is behind, so do not take the version from there. Each image is built for amd64 and arm64.

Only move the tag forward. Every start applies the image’s database schema, and by default it does so with prisma db push --accept-data-loss. Starting an image older than the one that last ran can drop columns the newer release added. Backups and upgrades covers upgrades and the safer migration mode.

Run the image without Compose

If PostgreSQL, Redis and a Temporal server already run elsewhere, you can run the image on its own. Keep the settings in a file and pass it with --env-file:

postqueen.env

MAIN_URL=https://postqueen.example.com
FRONTEND_URL=https://postqueen.example.com
NEXT_PUBLIC_BACKEND_URL=https://postqueen.example.com/api
BACKEND_INTERNAL_URL=http://localhost:3000
JWT_SECRET=a-long-random-string
ENCRYPTION_KEY=another-long-random-string
DATABASE_URL=postgresql://user:password@your-postgres:5432/postqueen
REDIS_URL=redis://your-redis:6379
TEMPORAL_ADDRESS=your-temporal:7233
IS_GENERAL=true
RUN_CRON=true
STORAGE_PROVIDER=local
UPLOAD_DIRECTORY=/uploads
NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY=uploads

docker run -d --name postqueen \
  --env-file ./postqueen.env \
  --network your-network \
  -v postqueen-uploads:/uploads \
  -p 127.0.0.1:5000:5000 \
  ghcr.io/gkhankinay/postqueen-app:vX.Y.Z

--network has to be the Docker network your databases are on. On the default bridge, container names do not resolve, and the connection fails.
The host port is 5000 here, not 4007. Point your reverse proxy at localhost:5000.
Do not start from .env.example in the app repository. It is written for running from source: its addresses point at localhost:4200, RUN_CRON is commented out, and POSTQUEEN_GENERIC_OAUTH="false" counts as on, which replaces the Google sign-in button with an unconfigured single sign-on button.

Next steps

Channel developer apps

Each network’s app, variables and redirect URI.

Email

Resend or SMTP, so password resets and invitations arrive.

Uploads and storage

Media on the local disk, or in Cloudflare R2.

Backups and upgrades

The volumes to back up, and how to move to a newer image.

Start here

Install

Domain and HTTPS

Configure

Channel developer apps

Operate

Develop

What the stack starts

Where settings live

Apply a change

Settings most installs change

Pin the image

Run the image without Compose

Next steps

Channel developer apps

Email

Uploads and storage

Backups and upgrades

​What the stack starts

​Where settings live

​Apply a change

​Settings most installs change

​Pin the image

​Run the image without Compose

​Next steps

Channel developer apps

Email

Uploads and storage

Backups and upgrades

What the stack starts

Where settings live

Apply a change

Settings most installs change

Pin the image

Run the image without Compose

Next steps