From b128cf7ff9d043bfe00ff863203588f5b8317e60 Mon Sep 17 00:00:00 2001 From: Juan del Peral Date: Fri, 10 Apr 2026 10:40:48 -0300 Subject: [PATCH] feat(infra): add Dokploy template docs and variable mapping Add Dokploy onboarding documentation and template variable wiring so Arche can be imported and configured consistently in Dokploy projects. Made-with: Cursor --- infra/dokploy/README.md | 79 +++++++++++++++++++++++++++++++ infra/dokploy/arche/template.toml | 47 ++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100644 infra/dokploy/README.md create mode 100644 infra/dokploy/arche/template.toml diff --git a/infra/dokploy/README.md b/infra/dokploy/README.md new file mode 100644 index 00000000..f6b5a5c6 --- /dev/null +++ b/infra/dokploy/README.md @@ -0,0 +1,79 @@ +# Arche — Dokploy Template + +This directory contains a Dokploy blueprint-ready template for Arche. + +## Included files + +- `arche/docker-compose.yml`: runtime stack (`web`, `postgres`, `docker-socket-proxy`) +- `arche/template.toml`: Dokploy variables, domain wiring, and env mapping +- `arche/instructions.md`: deployment prerequisites, deploy steps, and troubleshooting + +## Local import into Dokploy + +1. In Dokploy, create/import a template using these files. +2. Use `arche/template.toml` and `arche/docker-compose.yml`. +3. Follow `arche/instructions.md`. + +## Required variable groups + +- Domain and app: + - `ARCHE_DOMAIN` + - `WEB_IMAGE` +- Secrets: + - `POSTGRES_PASSWORD` + - `ARCHE_SESSION_PEPPER` + - `ARCHE_ENCRYPTION_KEY` + - `ARCHE_INTERNAL_TOKEN` + - `ARCHE_GATEWAY_TOKEN_SECRET` + - `ARCHE_CONNECTOR_OAUTH_STATE_SECRET` +- Admin bootstrap: + - `ARCHE_SEED_ADMIN_EMAIL` + - `ARCHE_SEED_ADMIN_PASSWORD` +- Spawner/runtime: + - `OPENCODE_IMAGE` + - `OPENCODE_NETWORK` + - `KB_CONTENT_HOST_PATH` + - `KB_CONFIG_HOST_PATH` + +## Secret generation (optional manual override) + +If you prefer setting your own secrets instead of Dokploy-generated defaults: + +```bash +echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)" +echo "ARCHE_SESSION_PEPPER=$(openssl rand -base64 32)" +echo "ARCHE_ENCRYPTION_KEY=$(openssl rand -base64 32)" +echo "ARCHE_INTERNAL_TOKEN=$(openssl rand -base64 32)" +echo "ARCHE_GATEWAY_TOKEN_SECRET=$(openssl rand -base64 32)" +echo "ARCHE_CONNECTOR_OAUTH_STATE_SECRET=$(openssl rand -base64 32)" +echo "ARCHE_SEED_ADMIN_PASSWORD=$(openssl rand -base64 18)" +``` + +## Validation checklist + +- `web` health endpoint returns 200 at `/api/health`. +- Admin login works with seeded credentials. +- New workspace can be created and started. +- Postgres has persistent data after stack restart. + +## Rollback + +- Redeploy the previous successful deployment in Dokploy. +- If image tags changed, roll back `WEB_IMAGE` and/or `OPENCODE_IMAGE` to prior known-good tags. + +## Publish to Dokploy templates repository + +Use the same structure as Dokploy blueprint examples (e.g. Ackee): +- `blueprints//docker-compose.yml` +- `blueprints//template.toml` +- `blueprints//instructions.md` +- `blueprints//logo.png` (optional but recommended) + +Suggested publish flow: +1. Copy `infra/dokploy/arche/*` to `blueprints/arche/`. +2. Add a `logo.png`. +3. Validate by deploying from a clean Dokploy project. +4. Open PR with: + - short description + - deploy screenshots/logs + - test notes for health, login, and workspace spawn diff --git a/infra/dokploy/arche/template.toml b/infra/dokploy/arche/template.toml new file mode 100644 index 00000000..7576436c --- /dev/null +++ b/infra/dokploy/arche/template.toml @@ -0,0 +1,47 @@ +[variables] +WEB_IMAGE = "ghcr.io/peaberry-studio/arche/web:latest" +POSTGRES_PASSWORD = "${password:32}" +ARCHE_DOMAIN = "${domain}" +ARCHE_SESSION_PEPPER = "${password:43}" +ARCHE_ENCRYPTION_KEY = "${password:43}" +ARCHE_INTERNAL_TOKEN = "${password:43}" +ARCHE_GATEWAY_TOKEN_SECRET = "${password:43}" +ARCHE_CONNECTOR_OAUTH_STATE_SECRET = "${password:43}" +ARCHE_GATEWAY_TOKEN_TTL_SECONDS = "86400" +ARCHE_GATEWAY_BASE_URL = "http://web:3000" +ARCHE_COOKIE_SECURE = "true" +ARCHE_SEED_ADMIN_EMAIL = "admin@example.com" +ARCHE_SEED_ADMIN_PASSWORD = "${password:20}" +ARCHE_SEED_ADMIN_SLUG = "admin" +OPENCODE_IMAGE = "ghcr.io/peaberry-studio/arche/workspace:latest" +OPENCODE_NETWORK = "arche_internal" +KB_HOST_PATH = "" +KB_CONTENT_HOST_PATH = "/opt/arche/kb-content" +KB_CONFIG_HOST_PATH = "/opt/arche/kb-config" + +[config] +[[config.domains]] +serviceName = "web" +port = 3000 +host = "${domain}" + +[config.env] +WEB_IMAGE = "${WEB_IMAGE}" +POSTGRES_PASSWORD = "${POSTGRES_PASSWORD}" +ARCHE_DOMAIN = "${ARCHE_DOMAIN}" +ARCHE_SESSION_PEPPER = "${ARCHE_SESSION_PEPPER}" +ARCHE_ENCRYPTION_KEY = "${ARCHE_ENCRYPTION_KEY}" +ARCHE_INTERNAL_TOKEN = "${ARCHE_INTERNAL_TOKEN}" +ARCHE_GATEWAY_TOKEN_SECRET = "${ARCHE_GATEWAY_TOKEN_SECRET}" +ARCHE_CONNECTOR_OAUTH_STATE_SECRET = "${ARCHE_CONNECTOR_OAUTH_STATE_SECRET}" +ARCHE_GATEWAY_TOKEN_TTL_SECONDS = "${ARCHE_GATEWAY_TOKEN_TTL_SECONDS}" +ARCHE_GATEWAY_BASE_URL = "${ARCHE_GATEWAY_BASE_URL}" +ARCHE_COOKIE_SECURE = "${ARCHE_COOKIE_SECURE}" +ARCHE_SEED_ADMIN_EMAIL = "${ARCHE_SEED_ADMIN_EMAIL}" +ARCHE_SEED_ADMIN_PASSWORD = "${ARCHE_SEED_ADMIN_PASSWORD}" +ARCHE_SEED_ADMIN_SLUG = "${ARCHE_SEED_ADMIN_SLUG}" +OPENCODE_IMAGE = "${OPENCODE_IMAGE}" +OPENCODE_NETWORK = "${OPENCODE_NETWORK}" +KB_HOST_PATH = "${KB_HOST_PATH}" +KB_CONTENT_HOST_PATH = "${KB_CONTENT_HOST_PATH}" +KB_CONFIG_HOST_PATH = "${KB_CONFIG_HOST_PATH}"