octopize.deploy_tool 3.0.0__tar.gz → 3.2.0__tar.gz

octopize_deploy_tool-3.2.0/PKG-INFO

@@ -0,0 +1,593 @@
+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