multica deployment

2026-10-20 13:41:11 -05:00
1 parent 63c5f7eed7
commit 39e2b87941
@@ -0,0 +1,61 @@
+# multica_docker
+
+Deploys [Multica](https://multica.ai/docs/self-host-quickstart) (Docker Compose self-host) and a containerised
+[Caddy](https://caddyserver.com) reverse proxy with automatic HTTPS.
+
+Mirrors the official quickstart: clones the repo, creates `.env` from `.env.example` (first run only, like
+`make selfhost`), manages specific keys in it, runs `docker-compose.selfhost.yml`, waits for `/readyz`, then
+fronts it with Caddy using the documented single-origin or two-domain config.
+
+## Requirements
+
+- Docker Engine + Compose v2 on the target (the role checks; it does not install Docker)
+- `ansible-galaxy collection install -r requirements.yml` (needs `community.docker >= 3.10`)
+- DNS for your hostname(s) pointing at the target
+
+## Quick start
+
+```bash
+cp group_vars/multica/vault.yml.example group_vars/multica/vault.yml   # fill in, then:
+ansible-vault encrypt group_vars/multica/vault.yml
+# edit inventory.ini + group_vars/multica/vars.yml
+ansible-playbook deploy_multica.yml --ask-vault-pass
+```
+
+## Key variables
+
+| Variable | Default | Notes |
+|---|---|---|
+| `multica_layout` | `single` | `single` = one hostname; `split` = app + api hostnames |
+| `multica_domain` | – | Hostname for `single` |
+| `multica_app_domain` / `multica_api_domain` | – | Hostnames for `split` |
+| `caddy_tls_mode` | `acme_http` | `acme_http`, `cloudflare_dns` (builds custom Caddy image), `internal` (Caddy CA, LAN only) |
+| `caddy_http_port` / `caddy_https_port` | `80` / `443` | Change if the host already runs nginx etc. |
+| `multica_version` / `multica_image_tag` | `main` / `latest` | Pin both to the same release tag for reproducible deploys |
+| `multica_pull_latest` | `false` | `true` pulls images every run (needed to move `latest`) |
+| `multica_backup_enabled` | `false` | `pg_dump` before changes to a running stack |
+| `multica_disable_telemetry` | `false` | Sets `DO_NOT_TRACK=true` |
+| `multica_extra_env` | `{}` | Extra `.env` keys, e.g. `ALLOW_SIGNUP: "false"` |
+
+Secrets (vault): `vault_multica_jwt_secret`, `vault_multica_postgres_password`, `vault_multica_vcs_secret_key`,
+`vault_cloudflare_api_token` (cloudflare_dns only), optional `vault_multica_resend_api_key`.
+
+## Behaviour worth knowing
+
+- **Idempotent**: `.env` is created once; only managed keys are rewritten. Compose recreates containers only when config changes.
+- **Ports 3000/8080 stay bound to 127.0.0.1** (as upstream intends). Caddy uses `network_mode: host` to reach them.
+- **Existing install?** The role overwrites `JWT_SECRET` (logs everyone out) and `POSTGRES_PASSWORD`. Postgres only reads its
+  password at first init, so for an existing database copy the *current* values from `.env` into the vault.
+- **Upgrades**: `-e multica_backup_enabled=true -e multica_pull_latest=true` (or bump `multica_version`/`multica_image_tag`).
+  Migrations run automatically on backend start; the role waits for `/readyz`.
+- **Tags**: `multica_preflight`, `multica`, `caddy`, `multica_verify`.
+
+## After the play: connect a computer
+
+The daemon runs on the machine with your AI coding tools, not the server:
+
+```bash
+multica setup self-host --server-url https://<domain> --app-url https://<domain>   # single layout
+```
+
+First login code (no email configured): `docker compose -f docker-compose.selfhost.yml logs backend | grep "Verification code"`