init-deployment.sh Script Reference#

This reference describes the init-deployment.sh script that initializes a Dioptra deployment. The script is located in the root of the deployment folder generated by the cookiecutter template.

See also

Prepare Your Deployment - Step-by-step guide for creating and customizing your deployment.

Overview#

The init-deployment.sh script automates the following initialization steps:

  • Generates random passwords used to secure Dioptra’s services

  • Copies and bundles extra CA certificates for the containers

  • Copies configuration files and certificates into named volumes

  • Sets appropriate file and folder access permissions

  • Initializes the persistent API signing key before database migrations and API startup

  • Creates RustFS S3 accounts and configures their access permissions

  • Syncs built-in task plugins from the Dioptra GitHub repository

  • Enables SSL/TLS in PostgreSQL (if applicable)

Secrets#

Initialization manages host credential files and a separate persistent API signing key. The credential paths below are relative to the generated deployment directory.

Host Credential Files#

The following files form one credential set:

  • .env

  • secrets/postgres-passwd.env

  • secrets/<deployment-slug>-rustfs-accounts.env

Credential-set handling#

Condition

Result

All three files are absent.

Generate the complete set with mode 0600 (owner read/write only).

All three files exist and are nonempty.

Preserve contents and ownership, repair permissions to 0600 and report repairs without logging credentials.

The set is incomplete or empty; a path is linked, nonregular or cannot be secured.

Stop initialization.

Existing values are not checked for consistency across files or against running services. The generated systemd unit contains no credentials and is outside this file-permission policy.

Credential generation requires a POSIX filesystem supporting descriptor-relative operations, same-directory hard links and file/directory synchronization. The deployment user needs access to read the files, set their permissions and create files in the containing directories.

An interrupted run can leave partial credentials or protected temporary files named .<credential-name>.<random-token>.tmp beside their destinations. Temporary files contain secrets and are not removed automatically by a later run. Caught generation failures attempt to remove newly created files and report cleanup failures; hardware failure or forced termination can leave partial state. See Recover Deployment Credentials before removing files or rerunning initialization.

API Signing Key#

Property

Behavior

Initialization

Runs inside the REST API image; the host does not need an installed Dioptra package.

Storage

The persistent REST API data volume retains the key across container restarts.

Reruns

Preserve an existing valid key.

Failure

Stop before database migrations or API startup.

Command-Line Options#

Usage: init-deployment.sh [--enable-nginx-ssl] [--enable-postgres-ssl]
                          [--skip-rustfs-setup] [--branch <branch-name>]
                          [--worker-ssl-service [tfcpu|pytorchcpu]]
                          [--python <cmd>] [-h|--help]
–enable-nginx-ssl

Enable the SSL-enabled configuration settings for the NGINX container. Use this if you copied a server certificate and private key into the ssl/nginx/ folder.

–enable-postgres-ssl

Enable the SSL-enabled configuration settings for the PostgreSQL container. Use this if you copied a server certificate and private key into the ssl/db/ folder.

–skip-rustfs-setup

Skip RustFS service setup. Useful when making configuration changes that do not require reconciling storage accounts and policies. RustFS account initialization can also be rerun without duplicating policy attachments.

–branch <branch-name>

The Dioptra GitHub branch to use when syncing built-in task plugins and frontend files. Replace <branch-name> with the branch you want to use (e.g., main, dev). (default: main)

–python <cmd>

Command for invoking the Python interpreter. Must be Python 3.11 or greater with the jinja2 package installed. (default: python)

–worker-ssl-service [tfcpu|pytorchcpu]

Container image to use when bootstrapping the SSL named volumes for worker containers. (default: tfcpu)

-h, –help

Print the help message and exit.

Examples#

Note

Replace <branch-name> with the Dioptra branch that matches your container images (e.g., main for releases, dev for development builds).

Basic initialization:

./init-deployment.sh --branch <branch-name>

With NGINX SSL enabled:

./init-deployment.sh --branch <branch-name> --enable-nginx-ssl

With both NGINX and PostgreSQL SSL enabled:

./init-deployment.sh --branch <branch-name> --enable-nginx-ssl --enable-postgres-ssl

Rerunning after configuration changes:

./init-deployment.sh --branch <branch-name> --skip-rustfs-setup

Important

You must specify the --enable-nginx-ssl and --enable-postgres-ssl options each time you run the init-deployment.sh script. If you omit them on a subsequent run, SSL/TLS will be disabled for those services.

See also