octopize.deploy_tool 3.3.0__tar.gz → 3.5.0__tar.gz

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: octopize.deploy_tool
-Version: 3.3.0
+Version: 3.5.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
@@ -96,9 +96,12 @@ to be up, and `provision-admin` must run before `verify`. Both hold once `start`
 
 ## Command reference
 
-`--app-root` defaults to the current directory everywhere it is accepted. Every command and
-`tasks` sub-command takes `--verbosity {1,2}`, where `1` is essential (the default) and `2` is
-verbose. Every command's `--help` lists its full option set.
+`--app-root` defaults to the current directory everywhere it is accepted, and must be a directory
+the invoking user can read, write and enter — every command refuses a root-owned or otherwise
+inaccessible root up front rather than failing part-way through. It does not have to exist yet, as
+long as its parent is writable. Every command and `tasks` sub-command takes `--verbosity {1,2}`,
+where `1` is essential (the default) and `2` is verbose. Every command's `--help` lists its full
+option set.
 
 ### Everyday commands
 
@@ -279,7 +282,8 @@ answering "keep" for a file is still honoured and still blocks the apply.
 `migrate` also creates `user_config/` under the new app root, so a migrated deployment is shaped
 exactly like an installed one and `update --from-config` works the same way on both.
 
-> **Before migrating non-interactively**, make sure the legacy `.env` sets
+> **Before migrating non-interactively**, make sure the legacy `.env` sets `SMTP_HOST` (or pass
+> `USE_AWS_SMTP_PRESET: true`), and 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 keeps it with a warning that
 > the path is "not usable yet" — the migration completes, but nginx will not start until a
@@ -425,6 +429,9 @@ 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.
+- **`SMTP_HOST` is required too**, unless you set `USE_AWS_SMTP_PRESET: true` to take the AWS SES
+  settings Octopize provides. The example sets it; a `--non-interactive` run with neither stops at
+  `'SMTP_HOST' is required and no value was provided`.
 - **The TLS keys the tool reads are `NGINX_SSL_CERTIFICATE_PATH` and
   `NGINX_SSL_CERTIFICATE_KEY_PATH`.** Use those spellings.
 
@@ -515,14 +522,31 @@ docker run --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/
 
 ### Start
 
+`start` pulls the images the deployment needs, and two of them are private. The
+credentials `docker login` writes belong to the Docker _client_, so the login you did on
+the host is invisible to the client in this container: the extra `DOCKER_CONFIG` mount
+below is what gives them to it.
+
 ```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" \
+  -e DOCKER_CONFIG=/docker-config -v "$HOME/.docker:/docker-config:ro" \
   quay.io/octopize/deploy-tool:latest start --app-root /app-root
 ```
 
+If the host keeps its registry credentials in a credential helper — a `credsStore` entry
+in `~/.docker/config.json` — that mount carries no usable credential, because the helper
+is a program the container does not have. Write a configuration that holds the token
+itself, and mount that one instead:
+
+```bash
+mkdir -p ~/avatar-registry-login
+DOCKER_CONFIG=~/avatar-registry-login docker login quay.io
+# ... -e DOCKER_CONFIG=/docker-config -v "$HOME/avatar-registry-login:/docker-config:ro"
+```
+
 ### Stop
 
 ```bash
@@ -583,6 +607,11 @@ Notes:
   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.
+- **The app root has to come from a mount.** The deployment files are read by the Docker daemon
+  on the host, and the tool works out their host path from the container's own mounts, so
+  `-v "$(pwd)/avatar:/app-root"` needs no path to match. A directory that belongs to the
+  container itself (`/tmp/avatar`, say) is reachable by nothing but the tool, and `start`
+  refuses it rather than bring up a stack that cannot read its own secrets.
 - **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.
@@ -647,6 +676,17 @@ under `generated_files/`. Merge them into `.deployment_states/<vX>/generated/` a
 
 **`verify` reports "API key not found".** Run `tasks provision-admin` first.
 
+**An `install` was interrupted with Ctrl+C.** Run `install` again: it reports the incomplete
+configuration and asks `Resume the in-progress configuration (vN)?` Answering `y` continues
+where it stopped, keeping the answers already given; answering `n` starts the questionnaire
+again in a new version slot and leaves the interrupted one on disk. A `--non-interactive` run
+cannot answer, so it stops instead.
+
+**`start` reports that an image registry refused the credentials.** The credentials
+`docker login` writes belong to the Docker client, so a `start` run from the deploy-tool
+container does not have the ones you created on the host. The message names the mount to add —
+see [Running via Docker](#running-via-docker).
+
 **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

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/README.md

@@ -63,9 +63,12 @@ to be up, and `provision-admin` must run before `verify`. Both hold once `start`
 
 ## Command reference
 
-`--app-root` defaults to the current directory everywhere it is accepted. Every command and
-`tasks` sub-command takes `--verbosity {1,2}`, where `1` is essential (the default) and `2` is
-verbose. Every command's `--help` lists its full option set.
+`--app-root` defaults to the current directory everywhere it is accepted, and must be a directory
+the invoking user can read, write and enter — every command refuses a root-owned or otherwise
+inaccessible root up front rather than failing part-way through. It does not have to exist yet, as
+long as its parent is writable. Every command and `tasks` sub-command takes `--verbosity {1,2}`,
+where `1` is essential (the default) and `2` is verbose. Every command's `--help` lists its full
+option set.
 
 ### Everyday commands
 
@@ -246,7 +249,8 @@ answering "keep" for a file is still honoured and still blocks the apply.
 `migrate` also creates `user_config/` under the new app root, so a migrated deployment is shaped
 exactly like an installed one and `update --from-config` works the same way on both.
 
-> **Before migrating non-interactively**, make sure the legacy `.env` sets
+> **Before migrating non-interactively**, make sure the legacy `.env` sets `SMTP_HOST` (or pass
+> `USE_AWS_SMTP_PRESET: true`), and 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 keeps it with a warning that
 > the path is "not usable yet" — the migration completes, but nginx will not start until a
@@ -392,6 +396,9 @@ 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.
+- **`SMTP_HOST` is required too**, unless you set `USE_AWS_SMTP_PRESET: true` to take the AWS SES
+  settings Octopize provides. The example sets it; a `--non-interactive` run with neither stops at
+  `'SMTP_HOST' is required and no value was provided`.
 - **The TLS keys the tool reads are `NGINX_SSL_CERTIFICATE_PATH` and
   `NGINX_SSL_CERTIFICATE_KEY_PATH`.** Use those spellings.
 
@@ -482,14 +489,31 @@ docker run --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/
 
 ### Start
 
+`start` pulls the images the deployment needs, and two of them are private. The
+credentials `docker login` writes belong to the Docker _client_, so the login you did on
+the host is invisible to the client in this container: the extra `DOCKER_CONFIG` mount
+below is what gives them to it.
+
 ```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" \
+  -e DOCKER_CONFIG=/docker-config -v "$HOME/.docker:/docker-config:ro" \
   quay.io/octopize/deploy-tool:latest start --app-root /app-root
 ```
 
+If the host keeps its registry credentials in a credential helper — a `credsStore` entry
+in `~/.docker/config.json` — that mount carries no usable credential, because the helper
+is a program the container does not have. Write a configuration that holds the token
+itself, and mount that one instead:
+
+```bash
+mkdir -p ~/avatar-registry-login
+DOCKER_CONFIG=~/avatar-registry-login docker login quay.io
+# ... -e DOCKER_CONFIG=/docker-config -v "$HOME/avatar-registry-login:/docker-config:ro"
+```
+
 ### Stop
 
 ```bash
@@ -550,6 +574,11 @@ Notes:
   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.
+- **The app root has to come from a mount.** The deployment files are read by the Docker daemon
+  on the host, and the tool works out their host path from the container's own mounts, so
+  `-v "$(pwd)/avatar:/app-root"` needs no path to match. A directory that belongs to the
+  container itself (`/tmp/avatar`, say) is reachable by nothing but the tool, and `start`
+  refuses it rather than bring up a stack that cannot read its own secrets.
 - **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.
@@ -614,6 +643,17 @@ under `generated_files/`. Merge them into `.deployment_states/<vX>/generated/` a
 
 **`verify` reports "API key not found".** Run `tasks provision-admin` first.
 
+**An `install` was interrupted with Ctrl+C.** Run `install` again: it reports the incomplete
+configuration and asks `Resume the in-progress configuration (vN)?` Answering `y` continues
+where it stopped, keeping the answers already given; answering `n` starts the questionnaire
+again in a new version slot and leaves the interrupted one on disk. A `--non-interactive` run
+cannot answer, so it stops instead.
+
+**`start` reports that an image registry refused the credentials.** The credentials
+`docker login` writes belong to the Docker client, so a `start` run from the deploy-tool
+container does not have the ones you created on the host. The message names the mount to add —
+see [Running via Docker](#running-via-docker).
+
 **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

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "octopize.deploy_tool"
-version = "3.3.0"
+version = "3.5.0"
 description = "Deployment configuration tool for Octopize Avatar platform"
 readme = "README.md"
 requires-python = ">=3.13"

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/src/octopize_avatar_deploy/__init__.py

@@ -9,7 +9,7 @@ from .version_compat import (
     validate_template_version,
 )
 
-__version__ = "3.3.0"
+__version__ = "3.5.0"
 __all__ = [
     "SCRIPT_VERSION",
     "ConsolePrinter",

octopize_deploy_tool-3.5.0/src/octopize_avatar_deploy/app_root.py

@@ -0,0 +1,123 @@
+"""Validation of the deployment root supplied on the command line.
+
+Every command reads and writes under ``--app-root``: the versioned state
+documents, the rendered versions, ``generated_files/``, the secrets. A path the
+invoking user cannot enter, read or write is a dead end, and the failure
+otherwise surfaces deep inside a command as a bare ``PermissionError`` on some
+individual file — after secrets have already been generated. Checking it at the
+CLI boundary turns that into one actionable message before any work starts.
+
+Write access is only demanded of the commands that write: a deployment root left
+read-only can still be stopped, diffed and verified.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+from pathlib import Path
+
+from octopize_avatar_deploy.application._guards import CommandError
+
+_EXAMPLE_ROOT = "./app/avatar"
+
+
+class AppRootError(CommandError):
+    """Raised when the deployment root cannot be used by the current user."""
+
+
+def validate_app_root(app_root: Path, *, require_write: bool = True) -> Path:
+    """Return *app_root* with ``~`` expanded, once it is usable by this user.
+
+    A root that does not exist yet is fine — commands create it — provided the
+    nearest existing ancestor is a directory this user can write into.
+
+    Args:
+        app_root: The path the operator passed to ``--app-root``.
+        require_write: Whether this command writes under the root.
+
+    Raises:
+        AppRootError: If the path (or the directory it would be created in) is
+            not a directory, or lacks the access this command needs.
+
+    """
+    expanded = app_root.expanduser()
+
+    if expanded.is_symlink() and not expanded.exists():
+        raise AppRootError(
+            f"{expanded} is a broken symlink. Point --app-root at a real directory, "
+            f"e.g. {_EXAMPLE_ROOT}."
+        )
+
+    target = expanded
+    while not target.exists():
+        parent = target.parent
+        if parent == target:
+            break
+        target = parent
+
+    if not target.is_dir():
+        raise AppRootError(
+            f"{target} is not a directory. Point --app-root at a directory you own, "
+            f"e.g. {_EXAMPLE_ROOT}."
+        )
+
+    missing = [
+        label for mode, label in _required_access(require_write) if not os.access(target, mode)
+    ]
+    if not missing:
+        return expanded
+
+    user = _current_user()
+    owner = _owner(target)
+    subject = (
+        f"Deployment root {expanded}"
+        if target == expanded
+        else f"{expanded} cannot be created: {target}"
+    )
+    raise AppRootError(
+        f"{subject} is not {_join(missing)} by user {user!r} (owner: {owner!r}).\n"
+        f"Point --app-root at a directory your user owns, e.g. {_EXAMPLE_ROOT}, or fix "
+        f"this one:\n  {_remedy(target, expanded, user, owner)}"
+    )
+
+
+def _required_access(require_write: bool) -> list[tuple[int, str]]:
+    """The access modes the command needs, each paired with how to name it."""
+    if require_write:
+        return [(os.R_OK, "readable"), (os.W_OK, "writable"), (os.X_OK, "traversable")]
+    return [(os.R_OK, "readable"), (os.X_OK, "traversable")]
+
+
+def _remedy(target: Path, expanded: Path, user: str, owner: str) -> str:
+    """The one command that gets this user the access they are missing."""
+    if owner == user:
+        # Already theirs, so the mode bits are what stand in the way.
+        return f"chmod u+rwx {target}"
+    if target == expanded:
+        return f"sudo chown -R {user} {target}"
+    return f"sudo install -d -o {user} {expanded}"
+
+
+def _join(labels: list[str]) -> str:
+    if len(labels) == 1:
+        return labels[0]
+    return f"{', '.join(labels[:-1])} or {labels[-1]}"
+
+
+def _current_user() -> str:
+    try:
+        return getpass.getuser()
+    except OSError:
+        return f"uid {os.getuid()}"
+
+
+def _owner(path: Path) -> str:
+    try:
+        return path.owner()
+    except (KeyError, NotImplementedError, OSError):
+        pass
+    try:
+        return f"uid {path.stat().st_uid}"
+    except OSError:
+        return "unknown"

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/src/octopize_avatar_deploy/application/checks.py

@@ -306,7 +306,9 @@ class DeploymentStateCheck:
     Handles three cases:
 
     - **No state** — nothing to do, continue silently.
-    - **In-progress** — in interactive mode, offer to resume; in non-interactive mode,
+    - **In-progress** — in interactive mode, offer to resume; a declined resume
+      continues into a new version slot, because ``install`` is the fresh-install
+      command and has no flag that could ask for one. In non-interactive mode,
       fail by default.
     - **Completed** — in interactive mode, warn and ask for confirmation;
       in non-interactive mode, fail by default (destructive fresh install requires
@@ -371,11 +373,21 @@ class DeploymentStateCheck:
             f"Resume the in-progress configuration ({version_label})?",
             default=True,
             key="preflight.deployment_state_check.resume",
+            help_text=(
+                "Yes continues the interrupted questionnaire: the steps it already "
+                f"completed are kept and only the remaining ones are asked.\n"
+                "No starts the questionnaire again from the first question, in a new "
+                f"version slot. {version_label} stays on disk and is not deployed."
+            ),
         )
         if resume:
             return DeploymentStateCheckResult(state="in_progress", aborted=False, resume=True)
-        # Operator declined to resume — abort so they can decide what to do.
-        return DeploymentStateCheckResult(state="in_progress", aborted=True, resume=False)
+
+        self._printer.print(
+            f"Starting a fresh configuration in a new version slot. "
+            f"The interrupted {version_label} is kept and is not deployed."
+        )
+        return DeploymentStateCheckResult(state="in_progress", aborted=False, resume=False)
 
     def _handle_completed(self) -> DeploymentStateCheckResult:
         self._printer.print_warning(

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/src/octopize_avatar_deploy/application/commands/install_command.py

@@ -247,8 +247,8 @@ class InstallCommand:
 
         self._printer.print_success(
             f"Install complete. Version {version_label!r} is now deployed to "
-            f"{apply_result.output_dir}. "
-            "Run 'start' to bring up the stack."
+            f"{apply_result.output_dir}.\n"
+            f"Bring up the stack by running 'start' with --app-root {args.app_root}"
         )
 
         # 7. Name the python clients that work with this API version, so the

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/src/octopize_avatar_deploy/application/commands/migrate_command.py

@@ -378,8 +378,8 @@ class MigrateCommand:
 
         self._printer.print_success(
             f"Migration complete. Version {version_label!r} is now deployed to "
-            f"{apply_result.output_dir}. "
-            "Run 'start' to bring up the stack."
+            f"{apply_result.output_dir}.\n"
+            f"Bring up the stack by running 'start' with --app-root {args.app_root}"
         )
 
         # 6. Name the python clients that work with this API version. A legacy

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/src/octopize_avatar_deploy/application/commands/tasks/create_users.py

@@ -21,6 +21,11 @@ from octopize_avatar_deploy.application.authentik_env import (
 )
 from octopize_avatar_deploy.application.deployment_paths import DeploymentPaths
 from octopize_avatar_deploy.application.ports import EnvReader, HttpClient
+from octopize_avatar_deploy.authentik_user_types import (
+    EXTERNAL_USER_TYPE,
+    INTERNAL_USER_TYPE,
+    AuthentikUserType,
+)
 from octopize_avatar_deploy.cli_dependencies import CliDependencies
 from octopize_avatar_deploy.domain.validation import ValidationError as _ValidationError
 from octopize_avatar_deploy.domain.validation import validate_email
@@ -71,6 +76,7 @@ class AuthentikUser:
     email: str
     name: str
     is_active: bool
+    user_type: str
 
 
 @dataclass(frozen=True)
@@ -101,6 +107,13 @@ class UserSpec:
     email: str
     group: str  # Authentik group name
 
+    @property
+    def user_type(self) -> AuthentikUserType:
+        """The Authentik user type this user needs to exercise its group's rights."""
+        if self.group == ADMIN_GROUP_NAME:
+            return INTERNAL_USER_TYPE
+        return EXTERNAL_USER_TYPE
+
 
 @dataclass
 class ProvisionResult:
@@ -170,7 +183,8 @@ class CreateUsersClient(Protocol):
     """Authentik operations needed by :class:`UserProvisioner`."""
 
     def get_user_by_email(self, email: str) -> AuthentikUser | None: ...
-    def create_user(self, *, email: str) -> AuthentikUser: ...
+    def create_user(self, *, email: str, user_type: AuthentikUserType) -> AuthentikUser: ...
+    def set_user_type(self, *, user_pk: int, user_type: AuthentikUserType) -> None: ...
     def get_group_by_name(self, name: str) -> AuthentikGroup | None: ...
     def add_user_to_group(self, *, user_pk: int, group_pk: str) -> None: ...
     def get_email_stage_by_name(self, name: str) -> AuthentikEmailStage | None: ...
@@ -218,6 +232,15 @@ class AuthentikHttpClient:
             return None
         return resp.body if isinstance(resp.body, dict) else {}
 
+    def _patch(self, path: str, body: dict[str, Any]) -> None:
+        url = self._api_url(path)
+        try:
+            resp = self._http.patch_json(url, body, headers=self._headers)
+        except HttpConnectionError as exc:
+            raise AuthentikConnectionError(url, exc) from exc
+        if resp.status_code >= 400:
+            raise AuthentikAPIError(resp.status_code, str(resp.body), url)
+
     def get_user_by_email(self, email: str) -> AuthentikUser | None:
         resp = self._get("/core/users/", params={"search": email})
         for user_data in resp.get("results", []):
@@ -225,7 +248,7 @@ class AuthentikHttpClient:
                 return self._parse_user(user_data)
         return None
 
-    def create_user(self, *, email: str) -> AuthentikUser:
+    def create_user(self, *, email: str, user_type: AuthentikUserType) -> AuthentikUser:
         display_name = email.split("@", maxsplit=1)[0]
         body: dict[str, Any] = {
             "username": email,
@@ -233,6 +256,7 @@ class AuthentikHttpClient:
             "name": display_name,
             "path": "users",
             "is_active": True,
+            "type": user_type,
         }
         resp = self._post("/core/users/", body)
         if resp is None:
@@ -241,6 +265,9 @@ class AuthentikHttpClient:
             )
         return self._parse_user(resp)
 
+    def set_user_type(self, *, user_pk: int, user_type: AuthentikUserType) -> None:
+        self._patch(f"/core/users/{user_pk}/", {"type": user_type})
+
     def get_group_by_name(self, name: str) -> AuthentikGroup | None:
         resp = self._get("/core/groups/", params={"name": name})
         for group_data in resp.get("results", []):
@@ -272,6 +299,7 @@ class AuthentikHttpClient:
             email=data.get("email", ""),
             name=data.get("name", ""),
             is_active=data.get("is_active", True),
+            user_type=str(data.get("type", "")),
         )
 
 
@@ -340,11 +368,10 @@ class UserProvisioner:
     def _provision_one(self, spec: UserSpec, *, send_email: bool) -> ProvisionResult:
         existing = self._client.get_user_by_email(spec.email)
         if existing is not None:
-            self._printer.print(f"  {spec.email} — already exists, skipping")
-            return ProvisionResult(email=spec.email, status="exists")
+            return self._reconcile_existing(existing, spec)
 
         try:
-            user = self._client.create_user(email=spec.email)
+            user = self._client.create_user(email=spec.email, user_type=spec.user_type)
         except AuthentikAPIError as exc:
             self._printer.print_error(f"  {spec.email} — failed to create: {exc.detail}")
             return ProvisionResult(email=spec.email, status="error", detail=exc.detail)
@@ -386,6 +413,36 @@ class UserProvisioner:
 
         return ProvisionResult(email=spec.email, status="created")
 
+    def _reconcile_existing(self, user: AuthentikUser, spec: UserSpec) -> ProvisionResult:
+        """Leave an existing user alone, except to widen an admin to an internal account.
+
+        A user is never narrowed back to ``external``: the extra rights an internal
+        account carries may have been granted deliberately outside this tool.
+        """
+        if not (spec.user_type == INTERNAL_USER_TYPE and user.user_type == EXTERNAL_USER_TYPE):
+            self._printer.print(f"  {spec.email} — already exists, skipping")
+            return ProvisionResult(email=spec.email, status="exists")
+
+        try:
+            self._client.set_user_type(user_pk=user.pk, user_type=INTERNAL_USER_TYPE)
+        except AuthentikAPIError as exc:
+            self._printer.print_error(
+                f"  {spec.email} — already exists, but failed to convert to an "
+                f"internal user: {exc.detail}"
+            )
+            return ProvisionResult(
+                email=spec.email,
+                status="error",
+                detail=f"Conversion to internal user failed: {exc.detail}",
+            )
+
+        self._printer.print_success(
+            f"  {spec.email} — already exists, converted to an internal user"
+        )
+        return ProvisionResult(
+            email=spec.email, status="exists", detail="Converted to an internal user"
+        )
+
 
 # ---------------------------------------------------------------------------
 # Command

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/src/octopize_avatar_deploy/application/commands/update_command.py

@@ -369,8 +369,9 @@ class UpdateCommand:
 
         self._printer.print_success(
             f"Update complete. Version {version_label!r} is now deployed to "
-            f"{apply_result.output_dir}. "
-            "Run 'start' to bring up the stack and re-apply the Authentik blueprint."
+            f"{apply_result.output_dir}.\n"
+            "Bring up the stack and re-apply the Authentik blueprint by running "
+            f"'start' with --app-root {args.app_root}"
         )
 
         # 7. Last thing on screen: which python clients still work. The API

{octopize_deploy_tool-3.3.0 → octopize_deploy_tool-3.5.0}/src/octopize_avatar_deploy/application/configure_command.py

@@ -195,8 +195,9 @@ class ConfigureCommand:
             base_state = DeploymentStateDocument.new(metadata).with_items(preset.items)
 
         # 4. Run the configuration pipeline.
-        # Pass a checkpoint that persists partial state after each step so that
-        # an interrupted run can be resumed via --resume.
+        # Only an interactive run is checkpointed: a non-interactive one is
+        # re-runnable from its own inputs, and a partial document it left behind
+        # would make the next install ask about a session nobody can answer for.
         def _checkpoint(partial: DeploymentStateDocument) -> None:
             self._repository.save(args.app_root, target.version, partial)
 
@@ -204,7 +205,7 @@ class ConfigureCommand:
             app_root=args.app_root,
             base_state=base_state,
             interactive=args.interactive,
-            on_checkpoint=_checkpoint,
+            on_checkpoint=_checkpoint if args.interactive else None,
         )
 
         # 5. Persist.