Metadata-Version: 2.4
Name: octopize.deploy_tool
Version: 3.2.0
Summary: Deployment configuration tool for Octopize Avatar platform
Project-URL: Homepage, https://octopize.io
Project-URL: Documentation, https://docs.octopize.io/docs/deploying/self-hosted/self_installation
Project-URL: Repository, https://github.com/octopize/avatar
Project-URL: Issues, https://github.com/octopize/avatar/issues
Author-email: Octopize <contact@octopize.io>
License: MIT
Keywords: avatar,configuration,deployment,octopize
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.13
Requires-Dist: certifi>=2024.0.0
Requires-Dist: cryptography>=49.0.0
Requires-Dist: httpx2>=2.4.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pandas>=3.0.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: python-on-whales>=0.76.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich-argparse>=1.8.0
Requires-Dist: rich>=13.0.0
Description-Content-Type: text/markdown

# Octopize Avatar Deployment Tool

`octopize-deploy-tool` configures, generates and operates a self-hosted [Octopize
Avatar](https://octopize.io) 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](https://docs.docker.com/engine/install/linux-postinstall/).
- 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`](#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](#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](https://docs.astral.sh/uv/) if you do not have it, then run the tool straight from
PyPI — no permanent install needed:

```bash
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:

```bash
# 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

| Command     | Use when                                                                    |
| ----------- | --------------------------------------------------------------------------- |
| `install`   | Setting up a new Avatar deployment for the first time                       |
| `update`    | Upgrading to a newer Avatar release, or changing a configuration value      |
| `start`     | Bringing a configured deployment live, or restarting it after a host reboot |
| `stop`      | Suspending the stack temporarily — containers and volumes are preserved     |
| `uninstall` | Permanently destroying the deployment and all of its data                   |
| `migrate`   | Importing a deployment created by hand or by an older version of this tool  |

#### `install`

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

```text
--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:

```text
⚠ 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](#changing-a-configuration-value)).

```bash
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`](#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:

```text
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.

```bash
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`.

```bash
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.

```bash
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](#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.

| Task                      | Purpose                                                          |
| ------------------------- | ---------------------------------------------------------------- |
| `provision-admin`         | Creates the Avatar API key that `verify` reads                   |
| `create-users`            | Creates Authentik accounts and emails each user a setup link     |
| `reconcile-blueprint`     | Re-applies the deployed Authentik blueprint to the running stack |
| `create-self-signed-cert` | Generates a self-signed TLS certificate and key                  |
| `authentik-migrate`       | Imports users and organizations from Avatar into Authentik SSO   |

#### `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.

```bash
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.

```bash
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](#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.

| Command     | What it does                                                                     |
| ----------- | -------------------------------------------------------------------------------- |
| `configure` | Answers the questionnaire, saves `.deployment_states/vX/deployment_state.yaml`   |
| `render`    | Turns a saved state into files under `.deployment_states/vX/generated/`          |
| `apply`     | Copies a rendered version into `generated_files/` and moves `currently_deployed` |
| `diff`      | Shows what would change between two rendered versions                            |
| `verify`    | Checks the running stack: API health plus a live email test                      |

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.

```bash
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.

```bash
# 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:

```yaml
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
```

```bash
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

```text
./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:

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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.

```bash
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.

```bash
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:

```bash
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](https://github.com/octopize/avatar/blob/main/infra/deployment/deployment-tool/docs/authentik-migration.md).

## Troubleshooting

**Services fail to start.** Inspect the stack directly:

```bash
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](#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`](#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](https://github.com/octopize/avatar/blob/main/infra/deployment/deployment-tool/docs/authentik-migration.md)
  — CSV export path, foreign Authentik instances, API tokens
- [Telemetry](https://github.com/octopize/avatar/blob/main/infra/deployment/deployment-tool/docs/telemetry.md)
  — what is sent, and how to enable, rotate or disable it
- [Debugging Authentik blueprints](https://github.com/octopize/avatar/blob/main/infra/deployment/deployment-tool/docs/debugging-blueprints.md)
  — when SSO configuration does not take effect
- [Network topology](https://github.com/octopize/avatar/blob/main/infra/deployment/deployment-tool/docs/network-topology.md)
  — the Compose networks and which services sit on which
