Two applications, because the console is a separate repository:
| App | Repository | Dockerfile | Port | Health |
|---|---|---|---|---|
| gateway | an1ndra/path |
Dockerfile (repo root) |
8080 | /actuator/health |
| console | an1ndra/path-admin |
Dockerfile (repo root) |
8080 | /healthz |
Either deploy the gateway as a Compose stack (compose.yml here, brings Postgres and
optional Valkey) or as a plain Application pointing at the Dockerfile with an external
database. The console is always a plain Application.
- Dokploy → Create → Compose.
- Source: GitHub →
an1ndra/path, branchmain. - Compose path:
deploy/dokploy/compose.yml. - Trigger Type: On Tag, with auto-deploy enabled. The gateway is a production
service; a pull request or a push to
Developmust not restart it. A release tag (v0.2.3) is the only thing that deploys — see "When it deploys" below. - Environment (the compose file references all of these):
POSTGRES_PASSWORD=<openssl rand -hex 24>
GATEWAY_MASTER_KEY=<openssl rand -base64 32> # keep it: it decrypts stored provider keys
GATEWAY_ADMIN_TOKEN=<openssl rand -hex 32> # only for token auth; ignore with SSO
GATEWAY_CORS_ORIGINS=https://admin.example.com # omit if same hostname as the console- Domain: point
gw.example.comat port 8080, enable HTTPS. - Deploy. First boot logs
Gateway ready. Admin API: enabledand, if-P releasewas used, seeds four providers.
Dokploy is set to On Tag, not On Push. The release flow is:
Developis merged intomainthrough a pull request (the required checks run there).- A
vX.Y.Ztag is pushed on the merge commit. - The tag starts the GitHub release workflow (image scan, promotion to GHCR, release notes) and the Dokploy webhook (rebuild from that tag and restart).
Pushes to Develop, pull requests and Dependabot branches therefore never touch
production; only a tag does. If a deploy should be skipped for a tag, disable auto-deploy
before pushing it.
The compose builds from the tagged source (build: context: ../..) rather than pulling
:latest. That is deliberate: both webhooks fire at the same moment, so a :latest pull
would race the image build and could deploy the previous release. Building the tagged
commit cannot race and guarantees the running code matches the tag. The GHCR image remains
the artifact to run elsewhere (Kubernetes, another host) and the one Trivy gates.
Create → Application → repository an1ndra/path, build type Dockerfile, port
8080, then:
SPRING_PROFILES_ACTIVE=postgres
DB_URL=jdbc:postgresql://<host>:5432/path
DB_USER=path
DB_PASSWORD=<...>
GATEWAY_MASTER_KEY=<openssl rand -base64 32>
GATEWAY_API_DOCS=falseMount a volume at /app/data if you'd rather keep the H2 database and the master key on
disk than use Postgres.
- Dokploy → Create → Application, repository
an1ndra/path-admin, branchmain. - Build: Dockerfile (node build stage → nginx). Port 8080. Health:
/healthz. - Environment — one variable:
# Separate hostnames:
GATEWAY_URL=https://gw.example.com
# Or leave it EMPTY and route /admin-ui to this container on the gateway's hostname,
# which removes CORS entirely.
GATEWAY_URL=- Domain:
admin.example.com(or a path prefix on the gateway domain) and HTTPS.
If the console is on a different hostname from the gateway, the gateway must allow it:
GATEWAY_CORS_ORIGINS=https://admin.example.comExact origin, no trailing slash, no wildcard. X-Admin-Token is a custom header, so the
browser sends a preflight; PUT is allowed as of 0.2.3, which the console's settings screen
needs.
Same-hostname routing on Dokploy/Traefik:
Host(`path.example.com`) && PathPrefix(`/admin-ui`) → console:8080 (strip prefix)
Host(`path.example.com`) → gateway:8080
- Put the console behind Cloudflare Access, Authentik or a VPN. A pasted admin token has
no second factor; see
docs/SSO.mdfor the proxy-auth mode that fixes that withGATEWAY_PROXY_AUTH=true. GATEWAY_API_DOCS=falsein production (the compose file sets it).- Keep
GATEWAY_MASTER_KEYin your password manager. Losing it means re-entering every provider credential. stop_grace_periodmust exceedGATEWAY_DRAIN_TIMEOUT, or a redeploy truncates live SSE streams (the compose file uses 40s against 25s).
The origin answers on its own public IP, so anyone can reach it directly and skip
Cloudflare — including its bot challenge and WAF rules. That is not hypothetical: an
external pentest used it to bypass rate limiting, and it makes every client-IP header
(CF-Connecting-IP, X-Forwarded-For) forgeable, which defeats per-address limits.
The compose file therefore attaches the cf-only Traefik middleware (Cloudflare's
published ranges) to the gateway router. Two things follow:
- The middleware itself lives in
/etc/dokploy/traefik/dynamic/middlewares.yml. Set it up once in Traefik File System; the compose label referencescf-only@file. - The console is a Dokploy application, so its router file is generated by Dokploy. After
any domain change there, re-add
- cf-onlyto thewebsecurerouter's middlewares, or the console is reachable directly again.
Verify with both halves — through Cloudflare and straight at the IP:
curl -fsS -o /dev/null -w '%{http_code}\n' https://gw.example.com/actuator/health # 200
curl -k -sS -o /dev/null -w '%{http_code}\n' --resolve gw.example.com:443:<origin-ip> \
https://gw.example.com/actuator/health # 403If you are not behind Cloudflare, use your CDN's ranges, or drop the middleware and accept that per-address limits can be spoofed.
curl -fsS https://gw.example.com/actuator/health # {"status":"UP"}
curl -fsS https://admin.example.com/healthz # ok
curl -fsS -H "X-Admin-Token: $TOKEN" https://gw.example.com/admin/settingsThen open the console, sign in, and Settings → Alert email → Send test email.