Skip to content

README.md

Latest commit

 

History

History
63 lines (49 loc) · 2.99 KB

README.md

File metadata and controls

63 lines (49 loc) · 2.99 KB

giuliosavini.arcane_stack.arcane_server

Deploys the Arcane server (control plane) as a Docker container.

What it does

  1. Ensures /opt/arcane and a .secrets/ sub-directory exist with locked-down permissions.
  2. Resolves ENCRYPTION_KEY and JWT_SECRET:
    • If you pass them via inventory / vault, those win.
    • Otherwise they're auto-generated on the first run via lookup('password') and persisted under .secrets/ so subsequent runs reuse the same values. Regenerating these invalidates the Arcane DB, so stability matters.
  3. Renders .env and docker-compose.yml from templates. Both notify a restart arcane_server handler, so the container is only recreated when config actually changes on disk.
  4. Runs docker compose up (idempotent via community.docker.docker_compose_v2) with configurable pull policy.
  5. Waits up to arcane_server_healthcheck_wait seconds for GET /api/health to return 200.

Every task is idempotent: re-running the playbook against a converged host is a no-op — no containers recreated, no secrets regenerated, no files rewritten.

Requirements

  • Docker Engine + compose plugin already installed on the target host.
  • Ansible collection community.docker >= 3.0.0.

This role intentionally does not install Docker — use geerlingguy.docker or your distro's package manager before running this role.

Role variables

See defaults/main.yml for the full list with inline docs. Quick reference:

Variable Default Purpose
arcane_server_image ghcr.io/getarcaneapp/arcane Container image
arcane_server_version latest Image tag (pin in production)
arcane_server_port 3552 Host port for the UI / API
arcane_server_app_url http://{{ ansible_host }}:3552 APP_URL inside the container
arcane_server_install_dir /opt/arcane Where compose + .env live
arcane_server_data_volume arcane-data Named volume for /app/data
arcane_server_extra_volumes [] Extra host-path mounts
arcane_server_puid / _pgid "" Optional runtime UID/GID
arcane_server_timezone UTC TZ for the scheduler
arcane_server_encryption_key "" → auto Stable 32-char secret
arcane_server_jwt_secret "" → auto Stable 48-char secret
arcane_server_pull_policy always always / missing / never
arcane_server_healthcheck_wait 60 Post-deploy probe timeout in s

Example

- hosts: arcane_server
  become: true
  roles:
    - role: giuliosavini.arcane_stack.arcane_server
      vars:
        arcane_server_version: "1.17.3"
        arcane_server_app_url: "https://arcane.example.com"
        arcane_server_extra_volumes:
          - host_path: /srv/projects
            container_path: /app/data/projects
          - host_path: /srv/builds
            container_path: /builds

License

MIT