Configuration
This page lists the environment variables of a Docker deployment. They end up in
generated_files/.env. Do not edit that file: set the values through the deploy tool's
questionnaire or a configuration file, as described in
Changing a value. Values marked Generated are derived or
created by the tool.
Core
| Variable | Default | Description |
|---|---|---|
PUBLIC_URL | Required | Bare domain name (no https://), for example avatar.company.com. Every public URL is derived from it. |
ENV_NAME | Required | Identifies the deployment for support. Lowercase letters, numbers and hyphens, for example company-prod. |
ORGANIZATION_NAME | Required | Name of your organization. |
Service URLs and endpoints
All of these are derived from PUBLIC_URL. They are listed so you can recognise them in .env.
| Variable | Example | Description |
|---|---|---|
AVATAR_DOMAIN | avatar.company.com | The bare domain, used by Nginx and Authentik. |
AVATAR_API_URL | https://avatar.company.com/api | Where users reach the API. |
AVATAR_WEB_CLIENT_URL | https://avatar.company.com | Where users reach the web client. |
AVATAR_STORAGE_ENDPOINT_PUBLIC_URL | https://avatar.company.com/storage | Public S3 endpoint for uploads and downloads. |
AVATAR_STORAGE_ENDPOINT_INTERNAL_URL | http://s3:8333 | S3 endpoint inside the Compose network. |
SSO_PROVIDER_URL | https://avatar.company.com/sso | Public base URL of Authentik. |
| Variable | Default | Description |
|---|---|---|
COMPATIBILITY_MAPPING_URL | https://license.octopize.io/compatibility/compatibility_mapping.json | Where the API downloads the client compatibility mapping. Set it to disabled to make no outgoing request. An empty value falls back to the default. |
TLS and Nginx
| Variable | Default | Description |
|---|---|---|
NGINX_SSL_CERTIFICATE_PATH | ./tls/server.fullchain.crt | Host path of the PEM full-chain certificate. Use an absolute path. |
NGINX_SSL_CERTIFICATE_KEY_PATH | ./tls/private/server.decrypted.key | Host path of the unencrypted private key. Use an absolute path. |
NGINX_TLS_ENABLED | true | Set to false only for a local evaluation. |
NGINX_HTTP_PORT | 8080 | Port Nginx listens on when TLS is disabled. |
Storage
| Variable | Default | Description |
|---|---|---|
SHARED_STORAGE_PATH | s3://{user_id}/{expire_days}d | Where datasets and generated files are stored, in the bundled SeaweedFS. |
Datasets and generated files are deleted after 30 days by default. The retention period is set per organization: ask Octopize support to change it.
The storage encryption key and the S3 admin keys are generated into generated_files/.secrets/
and cannot be configured. Back them up with the rest of the deployment directory: without
storage_encryption_key, the stored files cannot be read.
SeaweedFS admin password
The SeaweedFS storage has an admin password for the user admin. It is in
generated_files/.secrets/seaweedfs_admin_password. The tool generates it on install, and on the
first update of a deployment that does not have one.
To set your own password, or to rotate it, give the new value to update. Then restart the
admin service, because start does not restart it for this change:
echo "seaweedfs_admin_password: $(openssl rand -hex 32)" > rotate.yaml
octopize-deploy-tool update --app-root ./app/avatar --from-config rotate.yaml
octopize-deploy-tool start --app-root ./app/avatar
docker compose -f ./app/avatar/generated_files/docker-compose.yml restart admin
rm rotate.yaml
Database
PostgreSQL runs as the db service, with its data in the avatar_postgres_data volume. It holds
two databases, Avatar's and Authentik's. Their names, roles and passwords are generated into
generated_files/.secrets/:
| Secret file | Typical value | Description |
|---|---|---|
db_name | avatar | Avatar database |
db_user / db_password | avatar | Role the API connects as |
db_admin_user / db_admin_password | avatar_dba | PostgreSQL superuser, used to create the databases and for backups |
authentik_database_name | authentik | Authentik database |
authentik_database_user / authentik_database_password | authentik | Role Authentik connects as |
Service versions
Each release of the deploy tool pins tested versions. Override them only when Octopize asks you to.
| Variable | Description |
|---|---|
AVATAR_API_VERSION | Avatar API image tag |
AVATAR_WEB_VERSION | Avatar web client image tag |
AVATAR_SEAWEEDFS_VERSION | SeaweedFS image tag |
AVATAR_AUTHENTIK_VERSION | Authentik image tag |
Logging and monitoring
| Variable | Default | Description |
|---|---|---|
IS_SENTRY_ENABLED | true | Send internal errors to Sentry. See Data sent to Octopize. |
LOG_LEVEL | INFO | One of DEBUG, INFO, WARNING, ERROR, CRITICAL. |
USE_CONSOLE_LOGGING | false | Human-readable logs instead of JSON. |
Email
| Variable | Default | Description |
|---|---|---|
SMTP_HOST | Required | SMTP server host name. Raw IP addresses are not accepted. |
SMTP_PORT | 587 | 587 (STARTTLS), 465 (implicit TLS) or 25 (plain). |
SMTP_USE_TLS | true | Connect over TLS. |
SMTP_START_TLS | false | Upgrade a plain connection to TLS, for example for Office 365. |
SMTP_VERIFY | true | Verify the server's certificate. Set to false for a self-signed SMTP certificate. |
SMTP_SENDER_EMAIL | noreply@octopize.io | The "from" address. Often the same as SMTP_USERNAME. |
SMTP_USERNAME | None | If the server requires authentication. |
SMTP_PASSWORD | None | If the server requires authentication. |
Example for an internal relay without TLS:
SMTP_HOST: smtp.company.internal
SMTP_PORT: 25
SMTP_USE_TLS: false
SMTP_VERIFY: false
Telemetry
Telemetry sends usage metadata to Octopize, never datasets. It lets Octopize support you faster and keep track of the versions you run. See why, and what is sent. It is enabled once all the values below are set. Octopize provides the bucket name and the two credentials.
| Variable / secret | Default | Description |
|---|---|---|
TELEMETRY_S3_ENDPOINT_URL | https://s3.fr-par.scw.cloud | Telemetry S3 endpoint |
TELEMETRY_S3_REGION | fr-par | Telemetry S3 region |
TELEMETRY_S3_BUCKET_NAME | Provided by Octopize | Your telemetry bucket |
telemetry_s3_access_key_id | Provided by Octopize | Secret file |
telemetry_s3_secret_access_key | Provided by Octopize | Secret file |
The questionnaire offers to enable telemetry on install and on every update while it is off.
If you do not have the credentials yet, skip them, then run update once you receive them.
Single sign-on (Authentik)
The tool sets up Authentik on the first start, from a bundled
blueprint. You normally only choose the administrator's email address. The other values are
generated, and listed here so you can recognise them.
Bootstrap
| Variable | Description |
|---|---|
AUTHENTIK_BOOTSTRAP_EMAIL | Email address of the Authentik administrator (akadmin). Asked during install. |
AUTHENTIK_BOOTSTRAP_PASSWORD | Generated. Password of akadmin. |
AUTHENTIK_BOOTSTRAP_TOKEN | Generated. Authentik API token, used by tasks create-users and by the API to revoke the keys of disabled users. |
Blueprint variables
| Variable | Default | Description |
|---|---|---|
AVATAR_AUTHENTIK_BLUEPRINT_DOMAIN | Generated | Same as AVATAR_DOMAIN. |
AVATAR_AUTHENTIK_BLUEPRINT_CLIENT_ID | Generated | OAuth2 client ID. The API reads the same value as SSO_CLIENT_ID. |
AVATAR_AUTHENTIK_BLUEPRINT_CLIENT_SECRET | Generated | OAuth2 client secret. The API reads the same value as SSO_CLIENT_SECRET. |
AVATAR_AUTHENTIK_BLUEPRINT_API_REDIRECT_URI | Generated | https://<AVATAR_DOMAIN>/api/login/sso/auth. |
AVATAR_AUTHENTIK_BLUEPRINT_API_WEBHOOK_URL | Generated | Where Authentik notifies the API that a user was disabled or deleted, so their API keys are revoked. |
AVATAR_AUTHENTIK_BLUEPRINT_SELF_SERVICE_LICENSE | expert | License given to users who sign up themselves: expert (all features) or free_trial (limited runs and features). |
SSO_PROVIDER_APP_NAME is avatar-api and must not change.