Dokploy
Dokploy project configuration, deployment flow, and responsibility split.
Dokploy
Dokploy manages Git-based deployments, environment variables, domain routing, and managed PostgreSQL on BYTEBITE-APP-01.
Verified: 2026-09-08
What Dokploy owns
| Responsibility | Owner |
|---|---|
| Git checkout and build triggers | Dokploy |
| Environment variable injection | Dokploy |
| Managed PostgreSQL service | Dokploy |
| Explicit domain → service routing (Traefik labels via UI) | Dokploy |
dokploy-network attachment for domain-enabled services | Dokploy |
| Preview Compose generation | Dokploy |
Application containers from compose.deploy.yml | Dokploy (build + run) |
migrate one-shot (no UI domain) | compose.deploy.yml |
What Dokploy does not own
| Component | Managed elsewhere |
|---|---|
Traefik container (dokploy-traefik) | Dokploy platform (host-level config) |
| Wildcard tenant routing | compose.deploy.yml Traefik labels |
| DNS-01 wildcard TLS wiring | Host filesystem + Traefik static config |
| Cloudflare DNS records | Cloudflare dashboard |
| Mail server | BYTEBITE-MAIL-01 (separate VM) |
Project configuration
| Setting | Value |
|---|---|
| Dokploy version | dokploy/dokploy:v0.30.5 |
| Project | ByteBite |
| Environment | staging |
| Compose application | ByteBite Staging |
| App name / prefix (observed) | bytebite-staging |
| Generated runtime project (example) | bytebite-staging-oc5ach |
| Repository | ByteBite |
| Branch | main |
| Compose path | compose.deploy.yml |
| GitHub connection | GitHub-ByteBiteCo |
| Trigger | On Push |
| Submodules | Off |
| Watch paths | Empty |
Generated suffixes (oc5ach, etc.) are Dokploy-generated and not stable. Do not hardcode them in documentation or automation.
Checkout path
Dokploy uses a generated checkout directory, for example:
/etc/dokploy/compose/bytebite-staging-oc5ach/code/The suffix changes if the project is recreated.
Preview Compose vs repository
Dokploy's Preview Compose may contain Traefik labels and network attachments not literally present in the repository's compose.deploy.yml. Dokploy injects:
- Traefik labels for domains configured through the UI
dokploy-networkfor services with UI-managed domains
The repository file also declares dokploy-network as an external network so the migrate one-shot can reach PostgreSQL (Dokploy does not inject that network onto services without a UI domain). Do not assign a Dokploy domain to migrate.
The repository file adds manual wildcard HostRegexp labels on storefront and api, plus higher-priority BasicAuth Host() routers for reserved staging hosts. Both sources combine at runtime; the compose BasicAuth routers are intended to take precedence on HTTPS.
Explicit staging domains (Dokploy UI)
| Domain | Service | Port |
|---|---|---|
staging.getbytebite.co | landing | 3003 |
luigi.staging.getbytebite.co | storefront | 3000 |
mario.staging.getbytebite.co | storefront | 3000 |
dashboard.staging.getbytebite.co | dashboard | 8080 |
api.staging.getbytebite.co | api | 3001 |
docs.staging.getbytebite.co | docs | 3002 |
dokploy.getbytebite.co | Dokploy | — |
staging.getbytebite.co is the staging landing host (ADR-022). Compose routes it to landing at priority 200, ahead of a leftover Dokploy UI router that may still name storefront. Move that UI domain onto landing (port 3003). Restaurant ordering stays on luigi and mario. The page is Coming Soon, Staging while BYTEBITE_DEPLOY_ENV=staging.
Same-origin /api routes on explicit hosts (StripPrefix /api):
| Host | Path | Target |
|---|---|---|
luigi.staging.getbytebite.co | /api/* | api:3001 |
mario.staging.getbytebite.co | /api/* | api:3001 |
dashboard.staging.getbytebite.co | /api/* | api:3001 |
Wildcard domains — why not Dokploy UI
Dokploy's domain UI rejected *.staging.getbytebite.co. Wildcard tenant routing is implemented manually through Traefik labels in compose.deploy.yml. This is a deliberate architecture decision.
See Traefik for wildcard router details.
PostgreSQL service
| Setting | Value |
|---|---|
| Image | postgres:18 |
| Display name (observed) | bytebite-staging-postgres |
| Generated hostname (example) | bytebite-staging-postgres-vmg94p |
| Database | bytebite |
| User | bytebite |
| Port | 5432 (internal only) |
DATABASE_URL is set in Dokploy and passed to the migrate and api services. Never document the password or full credential-bearing URL.
Upgrade considerations
Dokploy upgrades may recreate the dokploy-traefik container. Custom Traefik wiring for DNS-01 wildcard TLS (secret mount, CF_DNS_API_TOKEN_FILE, letsencrypt-cloudflare resolver) lives outside normal Compose deployment and may be lost on recreate.
See Operations and Disaster recovery.
Related
- Deployment — end-to-end deploy flow
- Staging deployment — operational runbook
- Traefik — routing layer
- Database — PostgreSQL service