Octopize Avatar Deployment Tool

octopize-deploy-tool configures, generates and operates a self-hosted Octopize Avatar deployment. It asks you a questionnaire, renders a complete Docker Compose stack (.env, docker-compose.yml, nginx config, secrets, SSO blueprints) into a versioned directory tree, and manages that stack's lifecycle. Deployment templates for each release ship inside the package, so nothing is fetched at runtime.

Requirements

On the host that will run Avatar:

• A Linux server — Ubuntu 22.04 LTS or later is recommended.
• docker (with the Compose plugin) and curl.
• The deploying user in the docker group — see Docker's post-installation steps.
• A domain name pointing at the host, plus a TLS certificate and private key for it. Both are required for HTTPS; for internal or test deployments the tool can generate a self-signed certificate (see tasks).
• Inbound access to port 443 when TLS is enabled, or to NGINX_HTTP_PORT (default 8080) when it is not.

To run the CLI itself you need Python 3.13 or newer, or the published Docker image (see Running via Docker). Older Python versions fail with an opaque dependency resolution error.

Docker proxy gotcha. If your Docker daemon or client is configured with an HTTP proxy, the Avatar containers silently fail to reach each other. Exclude the Compose subnet by adding "noProxy": "172.18.0.0/16" to the proxies.default block of /etc/docker/daemon.json or ~/.docker/config.json. The setting applies to newly created containers only.

Quick start

Install uv if you do not have it, then run the tool straight from PyPI — no permanent install needed:

curl -LsSf https://astral.sh/uv/install.sh | sh
uvx octopize-deploy-tool --help

Alternatively, pip install octopize-deploy-tool inside a virtual environment (most distributions refuse installs into the system Python, per PEP 668) puts octopize-deploy-tool on your PATH — the form used below. A complete first deployment:

# Answer the questionnaire and generate all deployment files.
octopize-deploy-tool install --app-root ./app/avatar
# Bring the stack up.
octopize-deploy-tool start --app-root ./app/avatar
# Create the accounts your users will log in with.
octopize-deploy-tool tasks create-users --app-root ./app/avatar \
  --admins admin@company.com --users alice@company.com,bob@company.com
# Provision the admin API key that `verify` reads.
octopize-deploy-tool tasks provision-admin --app-root ./app/avatar
# Check the API is healthy and email delivery works.
octopize-deploy-tool verify --app-root ./app/avatar --test-email you@company.com

These are the five commands the end-to-end suite runs, in this order, before tearing the deployment down with uninstall. Two ordering constraints matter: create-users needs Authentik to be up, and provision-admin must run before verify. Both hold once start has finished.

Command reference

--app-root defaults to the current directory everywhere it is accepted. Every command takes --verbosity {1,2} (2 is verbose) except tasks create-self-signed-cert. The older --verbose flag is deprecated in favour of --verbosity 2 and is unavailable on verify and on all tasks sub-commands. Every command's --help lists its full option set.

Everyday commands

install

Runs the full questionnaire, generates every deployment file, and leaves the stack ready to start. It starts nothing — run start afterwards.

--app-root PATH        Deployment root directory (default: current directory)
--from-config PATH     Seed configuration from a YAML config file
--non-interactive      Run without prompts; uses defaults or the config file
--verbosity {1,2}      1 = essential (default), 2 = verbose

Before doing anything, install looks for Avatar Docker volumes left over from an earlier deployment. If it finds any it refuses to run, in both interactive and non-interactive mode:

⚠ Volume 'avatar_postgres_data' already exists.
✗ A fresh install generates new credentials, and Postgres ignores them on a volume that already
  holds a database — the API and Authentik would not be able to start. Choose one of:
  • Keep the data — you need the deployment that created it. Run 'update' against its app root,
    or 'migrate --from-legacy' if it predates the versioned layout. Without its .secrets/ the
    data cannot be read.
  • Discard the data — run 'uninstall' against the old app root, or remove the volumes by hand:
    docker volume rm avatar_postgres_data
⚠ Install aborted during pre-flight checks.

There is deliberately no override. A fresh install writes new secrets, but Postgres only applies POSTGRES_USER/POSTGRES_PASSWORD while initialising an empty data directory — on a volume that already holds a cluster they are silently ignored, so nothing can authenticate and the stack never comes up. The volume names are fixed, so a collision is always this deployment's own data.

The expert commands (configure, render, apply) do not run this check.

update

Re-runs the configuration from your current state, re-renders every file with the templates bundled in the installed version of this tool, shows a diff, and applies it. Values you already answered are carried forward, so you are not asked again. --from-config PATH layers a YAML file over the current state (see Changing a configuration value).

octopize-deploy-tool update --app-root ./app/avatar
octopize-deploy-tool start  --app-root ./app/avatar   # restart with the new files

That start also re-applies the Authentik blueprint, so a changed SSO configuration takes effect — see tasks reconcile-blueprint.

If you edited anything under generated_files/ by hand, update shows the diff and asks per file. The default is no — your file is kept — and keeping any file blocks the apply, so update exits non-zero:

Accept new render for '.env' and discard your manual changes? [y/N]
⚠   .env: keeping your manual changes — apply aborted for this file.
⚠ One or more files were kept. Apply is blocked until conflicts are resolved.
   Merge manually, then run: octopize-deploy-tool apply --version <vX>

Merge your edits into the rendered copy in .deployment_states/<vX>/generated/, then run apply --version <vX>. Anything that should survive future updates belongs in a config file, not in generated_files/.

start and stop

start creates any missing Docker volumes and brings all services up. It is idempotent, so it is also how you restart after a reboot or after update. stop suspends the services without removing containers or volumes.

octopize-deploy-tool stop --app-root ./app/avatar

uninstall

Destructive and irreversible. Stops and removes all containers and networks, deletes every Docker volume including the database and uploaded files, and removes generated_files/, .deployment_states/ and user_config/. You are asked to confirm first; --force skips the prompt for scripted use, and --non-interactive requires --force.

octopize-deploy-tool uninstall --app-root ./app/avatar

migrate

Imports a deployment set up manually or with an older version of this tool. Point --from-legacy at the directory holding the existing .env and .secrets/; values readable from there are carried over and you are prompted for the rest. If --from-legacy is omitted the tool asks for it interactively.

octopize-deploy-tool migrate --app-root ./app/avatar-new --from-legacy ./app/avatar-old
octopize-deploy-tool start   --app-root ./app/avatar-new

Before migrating non-interactively, make sure the legacy .env sets NGINX_SSL_CERTIFICATE_PATH and NGINX_SSL_CERTIFICATE_KEY_PATH to paths that exist. Otherwise the run falls back to a relative built-in default and fails with Invalid default value for 'NGINX_SSL_CERTIFICATE_PATH', and --non-interactive offers no way to supply one.

See Upgrading from a pre-SSO deployment for what happens to existing user accounts.

tasks

One-off operational sub-commands. All are idempotent and safe to re-run.

tasks provision-admin

Waits for Authentik and the Avatar API to become healthy, grants akadmin the admin role, logs in through Authentik's flow executor, creates an Avatar API key and writes it to generated_files/.secrets/avatar_api_key. verify fails without it. Re-running when the key file exists is a no-op; delete the file to force a rotation.

tasks reconcile-blueprint

Forces Authentik to apply the blueprint deployed under generated_files/authentik/ and waits for that apply to succeed. start runs it after an update, so you normally never call it yourself — run it if that step failed or was interrupted, which is when start prints this command.

octopize-deploy-tool tasks reconcile-blueprint --app-root ./app/avatar

An update changes what Authentik should be serving in two ways it cannot pick up by itself. A rewritten blueprint file is invisible to the containers that are already running, because a bind-mounted file stays pinned to the one they started with — so start recreates them after an update. A changed value the blueprint reads from the environment leaves the file untouched, and Authentik only re-applies a blueprint whose content changed — so the apply has to be forced. Either way nothing is reported as failed, which is why this runs unprompted. Applying an already-correct blueprint changes nothing.

tasks create-users

Creates accounts in Authentik using the bootstrap token from generated_files/.env, assigns each to the right group, and sends a branded recovery email so users set their own password without server-side browser access. Run it once the stack is up: the command does no readiness wait of its own, so Authentik must already be running with its blueprint applied. Existing users are detected and skipped.

Account creation and email delivery are independent — if the mail fails the account still exists, so a re-run skips that user. --no-email creates accounts silently. --authentik-url and --authentik-token override the values read from .env.

tasks create-self-signed-cert

Writes fullchain.crt (0644) and server.key (0600) for a domain, one or more IP addresses, or both. At least one of --domain or --ip-address is required — with neither, the command fails with Either --domain or --ip-address must be provided. --output-dir is created if missing (default: current directory) and existing files are overwritten after a warning. --valid-days defaults to 365.

octopize-deploy-tool tasks create-self-signed-cert \
  --domain avatar.company.com --ip-address 192.168.1.10 --output-dir /etc/nginx/certs

tasks authentik-migrate

Imports users, organizations and licenses from an existing Avatar database into Authentik. For a supported migrate you normally never run this by hand — see Upgrading from a pre-SSO deployment.

Expert commands

install, update and migrate are compositions of three lower-level commands. Use them directly when you want to inspect or stage a change before it goes live.

Each configure run creates a new version slot, so previous answers are never overwritten. Nothing you do with configure or render touches the running deployment until apply runs.

octopize-deploy-tool configure --app-root ./app/avatar --from-state v1
octopize-deploy-tool render    --app-root ./app/avatar --latest
octopize-deploy-tool diff      --app-root ./app/avatar deployed latest
octopize-deploy-tool apply     --app-root ./app/avatar --version v2

configure also accepts --from-config PATH, --from-legacy DIR, --resume (continue an interrupted session) and --fresh (force a new slot). render takes --version vX or --latest; apply requires --version vX. diff prints a per-file unified diff and prompts for each conflict exactly as update does; it takes positional refs — diff v3, diff v2 v3, diff deployed latest — or raw paths via --from / --to, and exits 0 when the versions are identical or every conflict was resolved, 1 when any file was skipped.

verify hits the Avatar API /health/config-full-check endpoint and sends a test email through the authentik_worker container. --test-email is required, the stack must be running, and tasks provision-admin must have run first — otherwise it reports API key not found in .../generated_files/.secrets/avatar_api_key. Run 'tasks provision-admin' first. Use --api-key to supply a key instead of reading one from disk.

Changing a configuration value

Put the values you want to change in a YAML file and hand it to update. They are layered over your current configuration: the keys you list win, everything else is carried forward unchanged.

# change.yaml holds only NGINX_SSL_CERTIFICATE_PATH and NGINX_SSL_CERTIFICATE_KEY_PATH
octopize-deploy-tool update --app-root ./app/avatar --from-config change.yaml
octopize-deploy-tool start  --app-root ./app/avatar

Do not edit files under generated_files/ — they are regenerated on every update, and an edit there becomes a conflict prompt that blocks the next apply.

Configuration file

install writes a commented reference to user_config/config.example.yaml under the app root. Copy it and fill in what you need: only the keys you set are used, everything else falls back to the built-in defaults. Its sections are PUBLIC_URL and ENV_NAME, then commented-out blocks for TLS and nginx, SMTP, service image versions, logging and telemetry.

Two things the example does not tell you:

• ORGANIZATION_NAME is missing from it and is required. A --non-interactive run without it stops at ORGANIZATION_NAME is required but not provided in configuration file. Add it yourself, as below.
• The TLS keys the tool reads are NGINX_SSL_CERTIFICATE_PATH and NGINX_SSL_CERTIFICATE_KEY_PATH. Use those spellings.

Storage credentials are not configurable at all — the encryption key and the S3 admin keys are generated for you into generated_files/.secrets/.

A minimal file that installs unattended, and how to use it:

PUBLIC_URL: avatar.example.com
ENV_NAME: company-prod
ORGANIZATION_NAME: MyCompany
NGINX_SSL_CERTIFICATE_PATH: /etc/ssl/avatar/server.crt
NGINX_SSL_CERTIFICATE_KEY_PATH: /etc/ssl/avatar/server.key

octopize-deploy-tool install --app-root ./app/avatar \
  --from-config ./app/avatar/user_config/config.yaml --non-interactive

If exactly one *.yaml or *.yml file other than config.example.yaml sits in user_config/ and --from-config was not given, install and update behave identically: interactively they ask whether to use it, non-interactively they print a notice and ignore it. Automated runs should always pass --from-config explicitly.

Generated files layout

./app/avatar/
├── .deployment_states/
│   ├── currently_deployed -> v1     # symlink, moved by `apply`
│   └── v1/
│       ├── deployment_state.yaml    # the answers, with the source of each value
│       └── generated/               # render staging area; `apply` copies out of here
├── user_config/                     # operator-owned; never overwritten by the tool
│   ├── config.example.yaml
│   ├── config.yaml                  # optional, yours to create
│   └── hooks/                       # reserved for future lifecycle hooks
└── generated_files/                 # what Docker Compose actually uses
    ├── .env
    ├── docker-compose.yml
    ├── nginx/nginx.conf
    ├── authentik/
    │   ├── octopize-avatar-blueprint.yaml
    │   ├── translations.json
    │   ├── custom-templates/
    │   └── branding/
    └── .secrets/                    # 18 generated secret files

Every update and migrate adds a new version slot (v2/, v3/, …), so previous states and renders stay on disk for reference and rollback.

Running via Docker

If Python 3.13+ is unavailable, or PyPI is blocked while quay.io is not, use the published image:

docker pull quay.io/octopize/deploy-tool:latest

Each block below is complete. Copy it as-is, changing only avatar (your deployment directory) and any value in <angle brackets>. The first line reads your Compose plugin path, which must be mounted at the same location inside the container.

Install — interactive

export CP=$(docker info -f '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}')
docker run -it --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -v "$(pwd)/avatar:/app-root" -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(which docker):/usr/local/bin/docker:ro" -v "$CP:$CP:ro" \
  quay.io/octopize/deploy-tool:latest install --app-root /app-root

Install — no prompts

export CP=$(docker info -f '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}')
docker run --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -v "$(pwd)/avatar:/app-root" -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(which docker):/usr/local/bin/docker:ro" -v "$CP:$CP:ro" \
  quay.io/octopize/deploy-tool:latest install --app-root /app-root \
  --from-config /app-root/user_config/config.yaml --non-interactive

Start

export CP=$(docker info -f '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}')
docker run --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -v "$(pwd)/avatar:/app-root" -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(which docker):/usr/local/bin/docker:ro" -v "$CP:$CP:ro" \
  quay.io/octopize/deploy-tool:latest start --app-root /app-root

Stop

export CP=$(docker info -f '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}')
docker run --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -v "$(pwd)/avatar:/app-root" -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(which docker):/usr/local/bin/docker:ro" -v "$CP:$CP:ro" \
  quay.io/octopize/deploy-tool:latest stop --app-root /app-root

Verify

export CP=$(docker info -f '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}')
docker run --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -v "$(pwd)/avatar:/app-root" -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(which docker):/usr/local/bin/docker:ro" -v "$CP:$CP:ro" \
  quay.io/octopize/deploy-tool:latest verify --app-root /app-root --test-email <you@company.com>

Uninstall — destroys the deployment and all its data

export CP=$(docker info -f '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}')
docker run -it --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -v "$(pwd)/avatar:/app-root" -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(which docker):/usr/local/bin/docker:ro" -v "$CP:$CP:ro" \
  quay.io/octopize/deploy-tool:latest uninstall --app-root /app-root

Update

Needs no Docker access, so no socket or plugin mounts.

docker run -it --rm --user "$(id -u):$(id -g)" \
  -v "$(pwd)/avatar:/app-root" \
  quay.io/octopize/deploy-tool:latest update --app-root /app-root

Migrate

Mount the old flat deployment read-only and pass its container path.

docker run -it --rm --user "$(id -u):$(id -g)" \
  -v "$(pwd)/avatar-new:/app-root" -v "$(pwd)/avatar-old:/legacy:ro" \
  quay.io/octopize/deploy-tool:latest migrate --app-root /app-root --from-legacy /legacy

Notes:

• The Docker CLI is not bundled in the image; the mounts above supply it and the Compose plugin. The official binary is statically linked and works across distributions.
• Anything outside the app root needs its own mount, always passed as its container path — e.g. -v "$(pwd)/config:/input:ro" with --from-config /input/config.yaml.
• Enter host paths at the prompts. Paths you type — TLS certificate, private key — are used by Docker Compose on the host, so give the host path even though you are typing it inside a container. The tool detects that it is running in a container, skips the existence check for those paths and prints a notice saying so.
• Anything outside the app root needs its own mount: -v "$(pwd)/config:/input:ro" with --from-config /input/config.yaml, or -v "$(pwd)/avatar-old:/legacy:ro" with --from-legacy /legacy for migrate. Always pass the container-side path.

Upgrading from a pre-SSO deployment

Older Avatar deployments kept users in the Avatar API database. migrate records that they still need importing into Authentik, and the first start after a migrate offers to do it for you: it previews every operation, asks for confirmation, and runs the import. Nothing has to be run by hand.

If you decline, the same import is available later:

octopize-deploy-tool tasks authentik-migrate --from-docker --app-root ./app/avatar

--from-docker reads users, organizations and licenses straight from the running api container's database, so there is no CSV export to produce; the extracted data is held in memory and never written to disk. The Authentik URL and token come from generated_files/.env. --dry-run previews without changing anything. Users that already carry an authentik_id are skipped, so the import is safe to re-run.

Every run that is not a --dry-run does write an operation log — migration_log.jsonl unless --log PATH says otherwise — recording what was attempted and how it ended. --from-log migration_log.jsonl --failed-only replays just the failures, into migration_log_retry.jsonl so the original is not overwritten.

If you are importing into an Authentik instance this tool did not deploy, or the api container is not running, export the three tables to CSV and pass them with --users, --orgs, --licenses, --authentik-url and --authentik-token instead. That path — the SQL to run, and how to mint an Authentik API token with the right permissions — is written up in Migrating users into Authentik.

Troubleshooting

Services fail to start. Inspect the stack directly:

docker compose -f ./app/avatar/generated_files/docker-compose.yml ps
docker compose -f ./app/avatar/generated_files/docker-compose.yml logs -f

Containers start but cannot reach each other. Almost always a Docker HTTP proxy — see the noProxy note under Requirements. Recreate the containers after fixing it; the setting does not affect existing ones.

install warns "Volume 'avatar_postgres_data' already exists". The host still holds data from a previous deployment. Use update to keep it or uninstall to destroy it. Answering y at the prompt installs on top of it with fresh credentials that will not match that data. A --non-interactive run does not offer the choice: it stops with Install aborted by operator during pre-flight checks.

update exits with "Apply is blocked until conflicts are resolved". You have manual edits under generated_files/. Merge them into .deployment_states/<vX>/generated/ and run apply --version <vX> — see update.

verify reports "API key not found". Run tasks provision-admin first.

Something needs a closer look. Add --verbosity 2 for detailed progress and template output.

Starting over. uninstall is the supported teardown: it is confirmation-gated and removes containers, volumes and deployment files together. Running docker compose down --volumes by hand deletes the Postgres volume — and every avatar, dataset and user account in it — while leaving the deployment files behind, so the two fall out of sync. Prefer uninstall.

Further information

• Deployment documentation: https://docs.octopize.io/docs/deploying/self-hosted/self_installation
• Package on PyPI: https://pypi.org/project/octopize-deploy-tool/
• Report a problem: https://github.com/octopize/avatar/issues

Reference documents live in the repository rather than in the published package, so they need access to https://github.com/octopize/avatar:

• Migrating users into Authentik — CSV export path, foreign Authentik instances, API tokens
• Telemetry — what is sent, and how to enable, rotate or disable it
• Debugging Authentik blueprints — when SSO configuration does not take effect
• Network topology — the Compose networks and which services sit on which