giuliosavini.arcane_stack

An opinionated, fully idempotent Ansible collection to deploy Arcane — a modern Docker management UI — across a control-plane host and any number of remote agent hosts, straight from your inventory.

Why this exists. Arcane is natively multi-host: one control-plane server + N remote agents running on your Docker boxes. That's exactly the shape Ansible was designed for. This collection wraps both sides into a single playbook you can re-run safely on every change — no more SSH'ing into five hosts to bump a version.

---

What's in the box

Two roles, wired to work together:

Role	What it deploys
arcane_server	Arcane server (control plane): compose stack, auto-generated secrets persisted on the target host, active /api/health probe
arcane_agent	Arcane headless agent (data plane): compose stack, registered against the server via AGENT_TOKEN

Plus three playbooks:

• playbooks/server.yml — server only
• playbooks/agent.yml — agents only
• playbooks/site.yml — server first, then agents (recommended)

Design principles

1. Strict idempotency. Re-running the playbook against a converged host is a no-op. Every task uses state: present, templates gate container restarts via handlers, and secrets are generated on the target host (not the control node) so you can run from CI, a different laptop, or a new control node without rotating keys.
2. Don't install Docker for you. Docker + compose are a prerequisite — use geerlingguy.docker in your playbook before these roles. Single-responsibility roles compose better.
3. Secrets can be auto-generated or passed via vault. On the first run, ENCRYPTION_KEY and JWT_SECRET are generated on the target host and cached under /opt/arcane/.secrets/. On every subsequent run the cached values are reused. For real deployments, pass the values explicitly via ansible-vault and they take precedence over the auto-generated ones.
4. Active healthcheck after deploy. The role probes GET /api/health for up to 60 seconds after docker compose up and fails loudly if Arcane doesn't come up.

Requirements

• Ansible: 2.15 or newer
• Collections:
  • community.docker >= 3.0.0
  • ansible.posix >= 1.5.0
• Target hosts:
  • Docker Engine + compose plugin already installed
  • Supported: Debian 11/12/13, Ubuntu 22.04/24.04, RHEL/Rocky/Alma 9

Install

ansible-galaxy collection install giuliosavini.arcane_stack

Or, while this is pre-release / from git:

ansible-galaxy collection install git+https://github.com/GiulioSavini/ansible-collection-arcane-stack.git

Quickstart

Create an inventory like inventory/example.yml:

all:
  vars:
    arcane_agent_manager_url: "http://arcane.lan:3552"
    arcane_agent_token: "{{ vault_arcane_agent_token }}"
    arcane_server_version: "1.17.3"
    arcane_agent_version: "1.17.3"

  children:
    arcane_server:
      hosts:
        arcane.lan:
    arcane_agents:
      hosts:
        docker01.lan:
          arcane_agent_name: "homelab-main"
        docker02.lan:
          arcane_agent_name: "media-server"

Put the real token in a vault file:

ansible-vault create group_vars/all/vault.yml
# vault_arcane_agent_token: "arc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Run the full rollout:

ansible-playbook -i inventory.yml \
  --ask-vault-pass \
  giuliosavini.arcane_stack.site

The site playbook brings up the server first, waits for /api/health to return 200, then deploys every agent in the arcane_agents group.

Re-running the same command is safe: you'll see changed=0 unless something actually drifted.

Role variables

See the per-role READMEs for the full list:

• arcane_server variables
• arcane_agent variables

Status

v0.1 — minimum viable release: server + agent deploy, idempotent secrets, active healthcheck.

Planned for v0.2:

• Pre-upgrade data-volume backup + retention
• Reverse proxy integration (Caddy / Traefik) with automatic HTTPS
• First-admin bootstrap via Arcane API
• Molecule test suite (Debian 12 + Ubuntu 24.04 containers)
• GitHub Actions CI + auto-publish on tag

Contributing

Issues and PRs welcome. If you're adding a feature, please keep the idempotency invariant: re-running the playbook on a converged host must remain a no-op.

License

MIT — see LICENSE.

Related

• Arcane — the Docker management UI this collection deploys
• community.docker — the compose module under the hood
• geerlingguy.docker — the Docker install role we recommend pairing with