Reference
Configuration (.env)
Every setting that lives in your .env file, grouped the way the file is. Copy
.env.example to .env, fill in the required values, and run
docker compose up -d. This page is the complete reference.
Keep .env private
It holds your secrets. It's already in .gitignore — never commit it. Only the
.env.example template is checked in.
How to read this page
- All platform settings use the reserved
ASTRODOCK_prefix. - required means a deploy or boot will complain until it's set. default shows the built-in fallback when you leave it blank.
- A few values are compose-managed — set for you by
docker-compose.yml. You normally don't put these in.envat all; they're listed at the end for reference.
Generating secrets
For every "random secret" below, generate a fresh value — don't reuse one. The easy way:
openssl rand -hex 32Run it once per secret (JWT secret, secret key, runner token, DB password, object-store key) and
paste the output into .env.
Domain / routing
Where your platform lives and how HTTPS is handled.
| Variable | What it does | Default / required |
|---|---|---|
ASTRODOCK_BASE_DOMAIN |
The base domain every app lives under: <subdomain>.<base-domain>.
Use localhost locally; your real domain on a server.
Leave blank to set it in the browser — with no domain, Astrodock boots into
first-run setup and serves the wizard over plain HTTP at http://<server-ip>.
Once set there it is stored in the database, and that stored value wins over this variable. |
blank — first-run setup |
ASTRODOCK_ADMIN_SUBDOMAIN |
The subdomain the dashboard is served at, giving <admin>.<base-domain>. |
admin |
ASTRODOCK_TLS_MODE |
How HTTPS works. auto = real Let's Encrypt certs (needs a public domain + DNS);
internal = Caddy's own CA (LAN / no public DNS; browser warns once);
off = plain HTTP (local / behind another proxy). |
internal (template ships auto) |
ASTRODOCK_ACME_EMAIL |
Contact email Let's Encrypt uses for certificate notices. Needed when
TLS_MODE=auto. |
empty |
ASTRODOCK_ALLOWED_ORIGIN_PATTERN |
Optional. A regex to override the CORS allowed-origin check. Leave blank and it's derived from your base domain (plus localhost outside production). | empty (derived) |
Admin login + secrets
Your dashboard login and the platform's internal secrets.
| Variable | What it does | Default / required |
|---|---|---|
ASTRODOCK_ADMIN_JWT_SECRET |
Signs your dashboard login session. A long random secret. | required |
ASTRODOCK_SECRET_KEY |
Master key that encrypts stored secrets at rest (AES-256-GCM). If unset, secrets are stored in plaintext and the control plane warns at boot. Strongly recommended. | strongly recommended |
ASTRODOCK_RUNNER_TOKEN |
Shared secret the control plane uses to authenticate to the runner over the internal network. A random secret. | required |
ASTRODOCK_ADMIN_EMAIL |
The email of the first admin, created on first boot. | required |
ASTRODOCK_ADMIN_PASSWORD |
The password for that first admin. Change it after logging in. | required |
Database (bundled Postgres)
Credentials for the Postgres that ships with Astrodock — it holds the control plane's data and any internal app databases.
| Variable | What it does | Default / required |
|---|---|---|
ASTRODOCK_PG_USER | Database user. | astrodock |
ASTRODOCK_PG_PASSWORD | Database password. A random secret. | required |
ASTRODOCK_PG_DATABASE | Database name. | astrodock |
Object store (bundled SeaweedFS)
Credentials for the bundled S3-compatible file storage. Apps in internal-storage mode receive these.
| Variable | What it does | Default / required |
|---|---|---|
ASTRODOCK_OBJECTSTORE_REGION | S3 region label. | us-east-1 |
ASTRODOCK_OBJECTSTORE_ACCESS_KEY | S3 access key (the "username"). | astrodock |
ASTRODOCK_OBJECTSTORE_SECRET_KEY | S3 secret key. A random secret. | required |
ASTRODOCK_OBJECTSTORE_BUCKET | Default bucket name. | astrodock |
GitHub (deploys)
Optional. Only needed if you want apps to deploy automatically on git push. Skip these
and you can still deploy from your laptop with --local.
| Variable | What it does | Default / required |
|---|---|---|
ASTRODOCK_GITHUB_PAT |
A fine-grained GitHub token (contents:read + repo webhooks read/write) the runner uses to pull code and manage webhooks. | empty (optional) |
ASTRODOCK_GITHUB_OWNER |
The GitHub org or user your app repos live under. | empty (optional) |
The PAT lives only on the runner
For safety, the GitHub token is held by the runner service, not the public-facing API — the compose file explicitly blanks it on the API container.
Email / alerts
Optional. Powers the health-monitor down/recovery emails via Resend. Leave blank to skip email.
| Variable | What it does | Default / required |
|---|---|---|
ASTRODOCK_EMAIL_FROM |
The "from" address/name for platform emails. | Astrodock <noreply@example.com> |
ASTRODOCK_ALERT_EMAIL |
Where down/recovery alerts are sent. | empty (optional) |
ASTRODOCK_RESEND_API_KEY |
Your Resend API key. Without it, no email is sent. | empty (optional) |
Step-by-step setup: Email notifications.
Pages
Optional — sensible defaults shown. The bucket is created automatically. See Pages.
| Variable | What it does | Default / required |
|---|---|---|
ASTRODOCK_PAGES_SUBDOMAIN | Subdomain Pages are served on (<sub>.<base-domain>). | pages |
ASTRODOCK_PAGES_BUCKET | Object-store bucket for page file bytes. | astrodock-pages |
ASTRODOCK_PAGE_DATA_MAX | Max size of a page's saved-data JSON blob (per page, or per page+user). | 1mb |
Pages need a wildcard, too
Pages live at pages.<base-domain>, which the same *.<base-domain>
wildcard DNS record already covers. No extra DNS needed.
Feature flags
| Variable | What it does | Default / required |
|---|
Leave the terminal off
The per-app terminal runs shell commands inside an app's context — effectively full access. Keep and accept the risk.
Compose-managed values (don't normally touch)
These are network-internal values set by docker-compose.yml so the services can find
each other. In the standard stack you shouldn't put them in .env —
they're listed here only so you know what they're for.
| Variable | What it does | Compose value |
|---|---|---|
ASTRODOCK_PG_HOST / ASTRODOCK_PG_PORT | Where the control plane reaches Postgres. | postgres : 5432 |
ASTRODOCK_PG_APP_HOST / ASTRODOCK_PG_APP_PORT | Where apps reach the bundled DB. | postgres : 5432 |
ASTRODOCK_OBJECTSTORE_ENDPOINT / ..._APP_ENDPOINT | The S3 endpoint for the platform and for apps. | http://objectstore:8333 |
ASTRODOCK_CADDY_ADMIN | Caddy's admin API, used to manage routes. | http://caddy:2019 |
ASTRODOCK_INTERNAL_AUTH_URL | The internal address apps call for /verify. | http://api:3100 |
ASTRODOCK_RUNNER_URL / ASTRODOCK_RUNNER_PORT | Where the control plane reaches the runner. | http://runner:3200 |
ASTRODOCK_DOCKER_NETWORK | The network Dockerfile-app containers join. | astrodock_default |
ASTRODOCK_ROLE | Which role the container runs as. | control-plane / runner |
ASTRODOCK_STATIC_DIR, ASTRODOCK_APPS_DIR, ASTRODOCK_REPOS_DIR, ASTRODOCK_CADDY_STATIC_DIR | The /data/… and /srv/… paths inside the containers. | set on the volumes |
PORT | The control plane's HTTP port. | 3100 |
When would I change these?
Almost never. They only matter if you're customising the compose topology — e.g. pointing at an external database (External database) or storage (External object storage), which those guides cover.
Related
- First-time setup with these values: Install & run
- Per-app variables (not platform config): Secrets & env vars
- Something not booting? Troubleshooting