homelab/ansible/roles/multica_docker/README.md

multica_docker

Deploys Multica (Docker Compose self-host) and a containerised Caddy 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

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:

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"