octopize.deploy_tool 2.2.0__tar.gz → 2.3.0__tar.gz

{octopize_deploy_tool-2.2.0 → octopize_deploy_tool-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: octopize.deploy_tool
-Version: 2.2.0
+Version: 2.3.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

{octopize_deploy_tool-2.2.0 → octopize_deploy_tool-2.3.0}/pyproject.toml

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

{octopize_deploy_tool-2.2.0 → octopize_deploy_tool-2.3.0}/src/octopize_avatar_deploy/__init__.py

@@ -11,7 +11,7 @@ from .version_compat import (
     validate_template_version,
 )
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 __all__ = [
     "main",
     "DeploymentRunner",

{octopize_deploy_tool-2.2.0 → octopize_deploy_tool-2.3.0}/src/octopize_avatar_deploy/defaults.yaml

@@ -1,6 +1,6 @@
 version: 1.0.0
 images:
-  api: 2.73.0
+  api: 2.77.0
   web: 0.63.0
   pdfgenerator: 0.2.3
   seaweedfs: "4.22"

octopize_deploy_tool-2.3.0/src/octopize_avatar_deploy/steps/authentik.py

@@ -0,0 +1,92 @@
+"""Authentik configuration step."""
+
+import secrets
+from typing import Any
+
+from .base import DeploymentStep, PromptConfig
+
+
+class AuthentikStep(DeploymentStep):
+    """Handles Authentik SSO configuration and credentials."""
+
+    name = "authentik"
+    description = "Configure Authentik SSO authentication credentials"
+
+    def collect_config(self) -> dict[str, Any]:
+        """Collect Authentik configuration."""
+        config = {}
+
+        self.printer.print("\n--- Authentik Configuration ---")
+        self.printer.print(
+            "This section configures Authentik, the identity and access management "
+            "service bundled with the Avatar deployment.\n"
+            "\n"
+            "Authentik is used to:\n"
+            "  - store and manage users\n"
+            "  - handle authentication and permissions\n"
+            "  - provide the login flow for Avatar\n"
+            "  - optionally connect to an existing identity provider or directory "
+            "service\n"
+            "\n"
+            "Depending on your setup, Authentik can also be integrated with existing "
+            "user management and SSO systems such as Microsoft Entra ID, Active "
+            "Directory, and other external identity providers.\n"
+            "\n"
+            "Authentik documentation:\n"
+            "https://docs.goauthentik.io/"
+        )
+
+        # Authentik database name and user
+        # These are typically set to default values unless customized
+        authentik_db_name = self.get_config("AUTHENTIK_DATABASE_NAME", "authentik")
+        authentik_db_user = self.get_config("AUTHENTIK_DATABASE_USER", "authentik")
+
+        config["AUTHENTIK_DATABASE_NAME"] = authentik_db_name
+        config["AUTHENTIK_DATABASE_USER"] = authentik_db_user
+
+        # Bootstrap configuration for automated install (skip OOBE)
+        # Default email for akadmin user
+        authentik_bootstrap_email = self.get_config_or_prompt_generic(
+            PromptConfig(
+                config_key="AUTHENTIK_BOOTSTRAP_EMAIL",
+                prompt_message="Enter email address for Authentik admin user (akadmin)",
+                default_value="admin@example.com",
+                prompt_key="authentik.bootstrap_email",
+                help_text=(
+                    "Email address of the initial Authentik administrator account created "
+                    "during bootstrap.\n"
+                    "\n"
+                    "This user will have full administrative access to the Authentik "
+                    "application. It can manage users, authentication flows, providers, "
+                    "integrations, and permissions.\n"
+                    "\n"
+                    "You can create additional super-admin users later if needed.\n"
+                    "\n"
+                    "No signup email is sent to this bootstrap administrator during "
+                    "installation. It is still recommended to use a real, reachable email "
+                    "address for operational clarity and future account management, but this "
+                    "is not strictly required.\n"
+                    "\n"
+                    "This email address can also be used to log in."
+                ),
+            )
+        )
+        config["AUTHENTIK_BOOTSTRAP_EMAIL"] = authentik_bootstrap_email
+
+        # Generate bootstrap credentials (these go in .env, not as secrets)
+        config["AUTHENTIK_BOOTSTRAP_PASSWORD"] = secrets.token_urlsafe(32)
+        config["AUTHENTIK_BOOTSTRAP_TOKEN"] = secrets.token_urlsafe(32)
+
+        # Update self.config so generate_secrets() can access these values
+        self.config.update(config)
+
+        return config
+
+    def generate_secrets(self) -> dict[str, str]:
+        """Generate Authentik-related secrets."""
+        return {
+            "authentik_database_name": self.config["AUTHENTIK_DATABASE_NAME"],
+            "authentik_database_user": self.config["AUTHENTIK_DATABASE_USER"],
+            "authentik_database_password": secrets.token_hex(),
+            "authentik_secret_key": secrets.token_hex(),
+        }

octopize_deploy_tool-2.3.0/src/octopize_avatar_deploy/steps/email.py

@@ -0,0 +1,178 @@
+"""Email configuration step."""
+
+import ipaddress
+from typing import Any
+
+from .base import (
+    DefaultKey,
+    DeploymentStep,
+    PromptConfig,
+    ValidationError,
+    ValidationSuccess,
+    parse_str,
+)
+
+
+def validate_smtp_host(value: str) -> ValidationSuccess[str] | ValidationError:
+    """
+    Validate that the SMTP host is a hostname or domain name, not a raw IP address.
+
+    An empty value is allowed (it means SMTP is not yet configured).
+
+    Args:
+        value: The SMTP host value to validate
+
+    Returns:
+        ValidationSuccess with the host string, or ValidationError with a message
+    """
+    host = str(value).strip()
+
+    if not host:
+        # Empty is allowed — the operator can leave SMTP unconfigured
+        return ValidationSuccess(host)
+
+    # Reject raw IP addresses (both IPv4 and IPv6)
+    try:
+        ipaddress.ip_address(host)
+        return ValidationError(
+            f"'{host}' is a raw IP address. "
+            "SMTP_HOST must be a hostname or domain name, not an IP address. "
+            "Examples: 'smtp.example.com', 'smtp.sendgrid.net', 'mail.example.com'."
+        )
+    except ValueError:
+        pass
+
+    return ValidationSuccess(host)
+
+
+class EmailStep(DeploymentStep):
+    """Handles email configuration and credentials."""
+
+    name = "email"
+    description = "Configure SMTP email settings and credentials"
+
+    def collect_config(self) -> dict[str, Any]:
+        """Collect email configuration."""
+        config = {}
+
+        print("\n--- Email Configuration ---")
+        self.printer.print(
+            "This section configures how the deployment sends outbound emails, mainly "
+            "for Authentik account and password workflows.\n"
+            "\n"
+            "The deployment needs an SMTP server to send emails such as account setup, "
+            "password reset, and other authentication-related messages.\n"
+            "\n"
+            "You can use:\n"
+            "  - your own SMTP provider or mail server\n"
+            "  - an SMTP service provided by Octopize, based on AWS\n"
+            "\n"
+            "If Octopize provides the SMTP service, we will give you the SMTP "
+            "credentials. In that case, the tool could eventually prefill the standard "
+            "connection settings and only ask you for the username and password we "
+            "provide."
+        )
+
+        # SMTP configuration
+        config["SMTP_HOST"] = self.get_config_or_prompt_generic(
+            PromptConfig(
+                config_key="SMTP_HOST",
+                prompt_message="SMTP host",
+                default_value=self.get_default_value("email.smtp.host"),
+                prompt_key="email.smtp_host",
+                parse_and_validate=validate_smtp_host,
+                help_text=(
+                    "Hostname of the outbound SMTP server used to send emails from the "
+                    "deployment.\n"
+                    "\n"
+                    "Use a mail server hostname or domain name, for example:\n"
+                    "  - smtp.gmail.com\n"
+                    "  - smtp.sendgrid.net\n"
+                    "  - mail.example.com\n"
+                    "\n"
+                    "Do not use an IP address here.\n"
+                    "\n"
+                    "This SMTP server is used by Authentik to send emails such as account "
+                    "setup and password reset messages."
+                ),
+            )
+        )
+        config["SMTP_PORT"] = self.get_config_or_prompt_generic(
+            PromptConfig(
+                config_key="SMTP_PORT",
+                prompt_message="SMTP port",
+                default_value=self.get_default_value("email.smtp.port"),
+                prompt_key="email.smtp_port",
+                parse_and_validate=parse_str,
+                help_text=(
+                    "TCP port for the SMTP connection.\n"
+                    "Common values:\n"
+                    "  587  — STARTTLS (recommended)\n"
+                    "  465  — TLS/SSL\n"
+                    "  25   — plain SMTP (often blocked by ISPs)"
+                ),
+            )
+        )
+        config["SMTP_USE_TLS"] = self.get_config("SMTP_USE_TLS", DefaultKey("email.smtp.use_tls"))
+        config["SMTP_START_TLS"] = self.get_config(
+            "SMTP_START_TLS", DefaultKey("email.smtp.start_tls")
+        )
+        config["SMTP_VERIFY"] = self.get_config("SMTP_VERIFY", DefaultKey("email.smtp.verify"))
+        config["SMTP_SENDER_EMAIL"] = self.get_config_or_prompt_generic(
+            PromptConfig(
+                config_key="SMTP_SENDER_EMAIL",
+                prompt_message="SMTP sender email",
+                default_value=self.get_default_value("email.smtp.sender_email"),
+                prompt_key="email.smtp_sender_email",
+                help_text=(
+                    "The From: address used for all outbound emails sent by the deployment.\n"
+                    "\n"
+                    "This address must be authorized to send through the configured SMTP "
+                    "server.\n"
+                    "\n"
+                    "In most cases, you should keep the default or the value recommended for "
+                    "your SMTP setup. Only change it if you have a specific need, for example "
+                    "if your SMTP provider requires the sender address to be the same as the "
+                    "SMTP username.\n"
+                    "\n"
+                    "Example:\n"
+                    "  - noreply@avatar.example.com"
+                ),
+            )
+        )
+        config["SMTP_USERNAME"] = self.get_config_or_prompt_generic(
+            PromptConfig(
+                config_key="SMTP_USERNAME",
+                prompt_message="SMTP username",
+                default_value="",
+                prompt_key="email.smtp_username",
+                help_text=(
+                    "Username for SMTP authentication. Leave blank if your server\n"
+                    "does not require authentication."
+                ),
+            )
+        )
+
+        self.config.update(config)
+
+        return config
+
+    def generate_secrets(self) -> dict[str, str]:
+        """Generate email-related secrets."""
+        secrets_dict = {}
+
+        if self.interactive:
+            smtp_password = self.prompt(
+                "SMTP password (press Enter to skip)",
+                default="",
+                key="email.smtp_password",
+                help_text=(
+                    "Password for SMTP authentication.\n"
+                    "\n"
+                    "Leave blank if your SMTP server does not require a password."
+                ),
+            )
+            if smtp_password:
+                secrets_dict["smtp_password"] = smtp_password
+
+        return secrets_dict

octopize_deploy_tool-2.3.0/src/octopize_avatar_deploy/steps/nginx.py

@@ -0,0 +1,188 @@
+"""Nginx TLS configuration step."""
+
+import socket
+from typing import Any
+
+from .base import DeploymentStep, PromptConfig, parse_bool
+
+
+def is_port_in_use(port: int) -> bool:
+    """Return True if something is already listening on *port* on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(1)
+        return sock.connect_ex(("127.0.0.1", port)) == 0
+
+
+class NginxTlsStep(DeploymentStep):
+    """Handles Nginx TLS configuration."""
+
+    name = "nginx_tls"
+    description = "Configure Nginx TLS and HTTP settings"
+
+    def collect_config(self) -> dict[str, Any]:
+        """Collect Nginx TLS and HTTP configuration."""
+        config: dict[str, Any] = {}
+
+        self.printer.print("\n--- Nginx / TLS Configuration ---")
+        self.printer.print(
+            "This section defines how users will reach the deployment through the Nginx "
+            "reverse proxy.\n"
+            "\n"
+            "Here you decide whether Nginx serves plain HTTP or terminates HTTPS/TLS "
+            "directly. If you enable TLS, you will need to provide the certificate and "
+            "private key files used by Nginx.\n"
+            "\n"
+            "If you plan to enable TLS here, the public URL you entered earlier should be "
+            "an HTTPS URL and should match the DNS name covered by your certificate."
+        )
+
+        default_tls_enabled = bool(self.get_default_value("nginx.tls_enabled"))
+        default_http_port = str(self.get_default_value("nginx.http_port"))
+        default_cert_path = self.get_default_value("nginx.ssl_certificate_path")
+        default_key_path = self.get_default_value("nginx.ssl_certificate_key_path")
+
+        # Use generic prompt with boolean parser and yes/no prompt
+        tls_enabled = self.get_config_or_prompt_generic(
+            PromptConfig(
+                config_key="NGINX_TLS_ENABLED",
+                prompt_message="Enable TLS for Nginx?",
+                default_value=default_tls_enabled,
+                prompt_key="nginx_tls.enabled",
+                prompt_function=self.prompt_yes_no,
+                parse_and_validate=parse_bool,
+                help_text=(
+                    "Enable this if Nginx should terminate HTTPS/TLS for the deployment.\n"
+                    "\n"
+                    "Choose yes only if:\n"
+                    "  - the public URL entered earlier is an https:// URL\n"
+                    "  - the DNS name for that URL points to this deployment\n"
+                    "  - you have a valid certificate and private key for that hostname\n"
+                    "\n"
+                    "If you enable TLS, the next prompts will ask for the certificate and "
+                    "key file paths used by Nginx.\n"
+                    "\n"
+                    "If your setup handles TLS elsewhere and Nginx should serve only plain "
+                    "HTTP locally, choose no."
+                ),
+            )
+        )
+
+        config["NGINX_TLS_ENABLED"] = tls_enabled
+
+        if tls_enabled:
+            cert_path = self.get_config_or_prompt_generic(
+                PromptConfig(
+                    config_key="NGINX_SSL_CERTIFICATE_PATH",
+                    prompt_message="Path to TLS certificate (full chain)",
+                    default_value=default_cert_path,
+                    prompt_key="nginx_tls.ssl_certificate_path",
+                    help_text=(
+                        "Path to the TLS certificate file that Nginx will present to clients.\n"
+                        "\n"
+                        "Use a PEM-formatted full-chain certificate file. This should include "
+                        "the server certificate and the intermediate certificates needed by "
+                        "clients.\n"
+                        "\n"
+                        "Expected input:\n"
+                        "  - a readable file path on the current machine\n"
+                        "  - PEM format\n"
+                        "  - full chain certificate\n"
+                        "\n"
+                        "If your certificate is currently in PKCS#12 format, convert it first:\n"
+                        "https://docs.octopize.io/docs/deploying/self-hosted/self_installation#convert-pkcs12-certificate-to-pem-format\n"
+                        "\n"
+                        "Recommended permissions:\n"
+                        "  - certificate file readable by the current user\n"
+                        "  - for example:\n"
+                        "      chmod 644 /app/avatar/tls/server.fullchain.crt\n"
+                        "\n"
+                        "Make sure the file exists and is readable by the current user running "
+                        "the deployment commands."
+                    ),
+                )
+            )
+
+            key_path = self.get_config_or_prompt_generic(
+                PromptConfig(
+                    config_key="NGINX_SSL_CERTIFICATE_KEY_PATH",
+                    prompt_message="Path to TLS private key (decrypted)",
+                    default_value=default_key_path,
+                    prompt_key="nginx_tls.ssl_certificate_key_path",
+                    help_text=(
+                        "Path to the TLS private key file that matches the certificate "
+                        "configured in the previous step.\n"
+                        "\n"
+                        "Use a decrypted private key in PEM format.\n"
+                        "\n"
+                        "Expected input:\n"
+                        "  - a readable file path on the current machine\n"
+                        "  - PEM format\n"
+                        "  - an unencrypted private key that Nginx can read at startup\n"
+                        "  - a key matching the configured certificate\n"
+                        "\n"
+                        "If your key is currently encrypted or bundled in a PKCS#12 archive, "
+                        "convert/export it first using the deployment documentation:\n"
+                        "https://docs.octopize.io/docs/deploying/self-hosted/self_installation#convert-pkcs12-certificate-to-pem-format\n"
+                        "\n"
+                        "Recommended permissions:\n"
+                        "  - private key readable by the current user\n"
+                        "  - private key kept as restrictive as possible\n"
+                        "  - for example:\n"
+                        "      chmod 600 /app/avatar/tls/private/server.decrypted.key\n"
+                        "\n"
+                        "Make sure the file exists and is readable by the current user running "
+                        "the deployment commands."
+                    ),
+                )
+            )
+
+            config["NGINX_SSL_CERTIFICATE_PATH"] = cert_path
+            config["NGINX_SSL_CERTIFICATE_KEY_PATH"] = key_path
+        else:
+            http_port = self.get_config_or_prompt_generic(
+                PromptConfig(
+                    config_key="NGINX_HTTP_PORT",
+                    prompt_message="HTTP port for Nginx",
+                    default_value=default_http_port,
+                    prompt_key="nginx_tls.http_port",
+                    help_text=(
+                        "TCP port on which Nginx will listen for plain HTTP traffic when TLS "
+                        "is disabled.\n"
+                        "\n"
+                        "If you press Enter, the default shown in the prompt will be used.\n"
+                        "\n"
+                        "Common choices:\n"
+                        "  - 8080 for a local or reverse-proxied setup\n"
+                        "  - 80 for a directly exposed HTTP service\n"
+                        "\n"
+                        "Choose a port that is reachable in your deployment setup and not "
+                        "already reserved by another service.\n"
+                        "\n"
+                        "This setting is only used when TLS is disabled in this tool."
+                    ),
+                )
+            )
+
+            config["NGINX_HTTP_PORT"] = http_port
+            config["NGINX_SSL_CERTIFICATE_PATH"] = "/dev/null"
+            config["NGINX_SSL_CERTIFICATE_KEY_PATH"] = "/dev/null"
+
+            try:
+                port_number = int(http_port)
+                if is_port_in_use(port_number):
+                    self.printer.print_warning(
+                        f"Port {http_port} appears to be already in use. "
+                        "This is expected if you are re-running the tool for an existing "
+                        "deployment, but may cause startup failures otherwise."
+                    )
+            except (ValueError, OSError):
+                # ValueError: http_port is not a valid integer (validation handled elsewhere).
+                # OSError: the socket probe itself failed (e.g. unusual network config).
+                # Neither case should block configuration; skip the check silently.
+                pass
+
+        return config
+
+    def generate_secrets(self) -> dict[str, str]:
+        """No secrets needed for Nginx TLS paths."""
+        return {}

{octopize_deploy_tool-2.2.0 → octopize_deploy_tool-2.3.0}/src/octopize_avatar_deploy/steps/required.py

@@ -1,11 +1,31 @@
 """Required configuration step - collects mandatory deployment settings."""
 
+import re
 import secrets
 from typing import Any
 
 from octopize_avatar_deploy.public_url import normalize_public_url
 
-from .base import DefaultKey, DeploymentStep, PromptConfig
+from .base import (
+    DefaultKey,
+    DeploymentStep,
+    PromptConfig,
+    ValidationError,
+    ValidationResult,
+    ValidationSuccess,
+)
+
+_ENV_NAME_SLUG_RE = re.compile(r"^[a-z0-9-]+$")
+
+
+def parse_env_name_slug(value: Any) -> ValidationResult[str]:
+    """Parse and validate ENV_NAME as a safe slug."""
+    env_name = str(value).strip()
+    if not env_name:
+        return ValidationError("ENV_NAME is required and cannot be empty")
+    if not _ENV_NAME_SLUG_RE.fullmatch(env_name):
+        return ValidationError("ENV_NAME must use lowercase letters, numbers, and hyphens only")
+    return ValidationSuccess(env_name)
 
 
 class RequiredConfigStep(DeploymentStep):
@@ -28,11 +48,25 @@ class RequiredConfigStep(DeploymentStep):
                     prompt_key="required_config.public_url",
                     parse_and_validate=normalize_public_url,
                     help_text=(
-                        "The publicly accessible URL for your Avatar deployment.\n"
+                        "The public URL that end users will use to access your Avatar "
+                        "deployment.\n\n"
                         "Accepted formats:\n"
                         "  avatar.example.com          (bare hostname — https:// is added)\n"
-                        "  https://avatar.example.com  (full URL)\n"
-                        "This value is used to build all service URLs and Authentik redirects."
+                        "  https://avatar.example.com  (full URL)\n\n"
+                        "Use the externally reachable DNS name for this deployment:\n"
+                        "  - the hostname that users will type in their browser\n"
+                        "  - the DNS name pointing to your deployment\n"
+                        "  - the hostname covered by your TLS certificate\n\n"
+                        "Do not use:\n"
+                        "  - an internal hostname\n"
+                        "  - a private IP address\n"
+                        "  - a public IP address\n\n"
+                        "Even if Avatar runs on a single machine, this value should usually "
+                        "be the public hostname exposed through Nginx, not the machine name "
+                        "itself. Nginx acts as the reverse proxy in front of the application "
+                        "services.\n\n"
+                        "This value is used to build the public service URLs and Authentik "
+                        "redirect URLs."
                     ),
                 )
             )
@@ -45,11 +79,29 @@ class RequiredConfigStep(DeploymentStep):
                 prompt_message="Environment name (e.g., mycompany-prod)",
                 default_value="",
                 prompt_key="required_config.env_name",
+                parse_and_validate=parse_env_name_slug,
                 help_text=(
-                    "A short slug that identifies this deployment environment.\n"
-                    "Examples: 'mycompany-prod', 'acme-staging', 'demo'\n"
-                    "Used in log labels, secret names, and the generated docker-compose"
-                    " project name."
+                    "A short technical name for this deployment environment.\n\n"
+                    "Examples:\n"
+                    "  - mycompany-prod\n"
+                    "  - acme-staging\n"
+                    "  - demo\n\n"
+                    "Use a stable, machine-friendly identifier that helps operators "
+                    "distinguish this deployment from others. This is not a user-facing "
+                    "label.\n\n"
+                    "It is written into the generated deployment configuration and passed to "
+                    "the services as an environment identifier.\n\n"
+                    "Recommended format:\n"
+                    "  - lowercase letters\n"
+                    "  - numbers\n"
+                    "  - hyphens\n\n"
+                    "Avoid:\n"
+                    "  - spaces\n"
+                    "  - special characters\n\n"
+                    "Typical patterns:\n"
+                    "  - customer-prod\n"
+                    "  - customer-staging\n"
+                    "  - internal-demo"
                 ),
             )
         )
@@ -63,9 +115,22 @@ class RequiredConfigStep(DeploymentStep):
                     "Organization name (e.g., MyCompany)",
                     key="required_config.organization_name",
                     help_text=(
-                        "The name of your organization as it will appear in the deployment.\n"
-                        "Examples: 'Acme Corp', 'MyCompany', 'Octopize'\n"
-                        "This value is embedded in generated secrets and config files."
+                        "A short organization identifier used by the deployment configuration.\n\n"
+                        "Examples:\n"
+                        "  - acme\n"
+                        "  - my-company\n"
+                        "  - octopize\n\n"
+                        "Use a single lowercase word or slug. Hyphens are allowed.\n\n"
+                        "Recommended format:\n"
+                        "  - lowercase letters\n"
+                        "  - numbers\n"
+                        "  - hyphens\n\n"
+                        "Avoid:\n"
+                        "  - spaces\n"
+                        "  - uppercase letters\n"
+                        "  - special characters\n\n"
+                        "This is a technical identifier used in generated secrets and "
+                        "configuration files, not a display name for end users."
                     ),
                 )
                 if org_name.strip():

{octopize_deploy_tool-2.2.0 → octopize_deploy_tool-2.3.0}/src/octopize_avatar_deploy/steps/telemetry.py

@@ -16,6 +16,21 @@ class TelemetryStep(DeploymentStep):
         """Collect telemetry configuration."""
         config = {}
 
+        self.printer.print("\n--- Telemetry Configuration ---")
+        self.printer.print(
+            "This section configures optional observability features for the deployment.\n"
+            "\n"
+            "Avatar can send:\n"
+            "  - error reports to Sentry, to help diagnose application failures\n"
+            "  - limited usage telemetry to Octopize licensing/support services\n"
+            "\n"
+            "According to the observability documentation, these flows send metadata "
+            "only, not user data or personal data.\n"
+            "\n"
+            "Documentation:\n"
+            "https://docs.octopize.io/docs/deploying/observability"
+        )
+
         default_sentry_enabled = self.get_default_value("application.sentry_enabled") == "true"
         sentry_enabled = self.get_config_or_prompt_generic(
             PromptConfig(
@@ -25,6 +40,15 @@ class TelemetryStep(DeploymentStep):
                 prompt_key="telemetry.enable_sentry",
                 prompt_function=self.prompt_yes_no,
                 parse_and_validate=parse_bool,
+                help_text=(
+                    "Enable this to send application errors to Sentry for diagnosis and "
+                    "support.\n"
+                    "\n"
+                    "This is used to help investigate failures and improve stability. "
+                    "According to the observability documentation, Sentry receives error "
+                    "metadata such as stack traces and environment information, but not user "
+                    "data or personal data."
+                ),
             )
         )
 
@@ -36,6 +60,15 @@ class TelemetryStep(DeploymentStep):
                 "Enable usage telemetry?",
                 default=default_telemetry_enabled,
                 key="telemetry.enable_telemetry",
+                help_text=(
+                    "Enable this to send limited usage telemetry to Octopize "
+                    "licensing/support services.\n"
+                    "\n"
+                    "This helps with license monitoring, support, and faster diagnosis of "
+                    "operational issues. According to the observability documentation, only "
+                    "metadata is sent, such as job kind, job name, and username. No user "
+                    "data, payload content, or personal data is sent."
+                ),
             )
             if self.interactive
             else default_telemetry_enabled