Deployment

Note: Prefer the per-app Coolify Compose files under deploy/coolify/ for production deployments. This docs/deployment/ folder is kept for human-readable guides and legacy stack examples.

Choose a deployment method that fits your environment:

Coolify on HelioHost VPS (Authoritative Per-App Setup)

Prefer the per-app Compose files under deploy/coolify/. The legacy monolithic stack in docs/deployment/coolify-config.yml is deprecated.

1) Prepare DNS

  • Create A records pointing to your VPS IP:
    • Docs: docs.digiplumb.dev (or your chosen docs domain)
    • API: api.<your-domain> → set as API_DOMAIN_NAME
    • Jaeger UI (legacy, optional): jaeger.<your-domain> → set as JAEGER_DOMAIN_NAME

2) Create apps in Coolify (one per component)

  • App: Docs → Repository path: deploy/coolify/docs.compose.yml
    • Domain is currently hardcoded in the compose as docs.digiplumb.dev.
    • Health: /health
  • App: API → Repository path: deploy/coolify/prism-api.compose.yml
    • Set env: API_DOMAIN_NAME, DATABASE_URL, REDIS_URL, RPC_URL, RUST_LOG, OTEL_EXPORTER_OTLP_ENDPOINT=http://coroot:8080/v1/traces
    • Health: /health
  • App: Observability (Jaeger - legacy) → Repository path: deploy/coolify/legacy/observability.compose.yml (optional UI exposure)
    • Note: deploy/coolify/observability.compose.yml is an empty stub pointing to the legacy file above.
    • Set env: JAEGER_DOMAIN_NAME if exposing UI via Traefik
  • App: SurrealDB → Repository path: deploy/coolify/surrealdb.compose.yml
    • Set env: SURREALDB_PASSWORD
  • App: Redis → Repository path: deploy/coolify/redis.compose.yml
    • Set env: REDIS_PASSWORD

All routed apps attach to the external Docker network coolify for Traefik.

3) Traefik / TLS Notes

  • Entrypoints: http, https.
  • Cert resolver: letsencrypt.
  • ACME e-mail must be valid (e.g., your Gmail). Traefik handles certificate issuance automatically.
  • If you see ${VAR} literally in Traefik logs, Coolify did not interpolate label env vars. Hardcode the domain in the compose file (as done in deploy/coolify/docs.compose.yml).

4) Configure GitHub Actions secrets (docs deploy)

Set in GitHub repo → Settings → Secrets and variables → Actions:

  • VPS_HOST (VPS hostname or IP)
  • VPS_USER (SSH user)
  • VPS_SSH_KEY (private key PEM; no passphrase or add support)
  • VPS_TARGET_PATH (e.g., /var/www/prism-docs)
  • DISCORD_WEBHOOK_URL (for notifications)

5) Deploy

  • In Coolify, deploy each app created above.
  • In GitHub, run workflow: “Docs Deploy to VPS” (or push to main).

6) Verify

  • Docs: https://<DOCS_DOMAIN_NAME> renders mdBook
  • Docs Health: GET https://<DOCS_DOMAIN_NAME>/health returns OK
  • API: GET https://<API_DOMAIN_NAME>/health returns 200 (valid cert)
  • Jaeger UI (legacy, optional): https://<JAEGER_DOMAIN_NAME>/ loads UI with valid cert
  • Discord channel shows workflow success/failure for docs deploy.

Notes

  • Caddy container serves /srv which is host-mounted from /var/www/prism-docs.
  • The docs workflow rsyncs the built book/ directory to VPS_TARGET_PATH.
  • StrictHostKeyChecking=no is used initially; consider pinning host key later for security.