62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
# 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"`
|