Prerequisites

Tools

Control node (local machine):

• uv
• ansible-galaxy (installed by uv sync) to pull requirements.yml: the community.general, community.crypto, ansible.posix, community.docker, community.postgresql, and arpanrec.nebula collections, and the geerlingguy.docker role
• SSH access to the target host, and a working sudo on both the control node and the target host
• git
• rsync, which the PyPI mirror and SCM stages use to push their Docker build contexts to the target host
• gitleaks, only if enabling the secret-scanning pre-commit hook (see DEVELOPMENT.md)

Target host:

• docker, with the daemon running
• rsync
• restic, for the SCM backup and restore
• ufw, which every service uses to open its ports
• an nftables-based firewall, since the SCM scm_fail2ban stage bans IPs with the nftables-allports action
• sudo privileges for the SSH user

The SCM prerequisites stage checks docker, restic, and rsync, and runs a sudo id on both the control node and the target host. The database prerequisites stage checks docker and runs a sudo id on the target host.

Vault access config

lookup_plugins/vault_lookup.py and the action plugin behind vault_downstream_db_credentials both read the Vault connection from environment variables. The SCM scm_post_install stage and the PyPI mirror pypi_mirror_install stage read the same variables to write generated secrets back.

CS_PROJECT_CODE="Project code, mandatory. Resolves to the Ansible variable cs_project_code, the Vault bucket name."
VAULT_API_ENDPOINT="API Endpoint, https://127.0.0.1:8083"
VAULT_API_KEY="API Key"
VAULT_CA_CERT_BASE64="Base64 encoded Vault CA certificate."
VAULT_CLIENT_CERT_BASE64="Base64 encoded Vault mTLS client certificate."
VAULT_CLIENT_KEY_BASE64="Base64 encoded Vault mTLS client private key."
DEBUG="Optional. Set to true to disable no_log and print secrets. Never in production."

The three *_BASE64 variables are decoded to temp files at runtime and used for mutual TLS against Vault. These variables can also be placed in a .env file in the project root. The lookup and action plugins load it via python-dotenv at import time.

Shared Vault configurations

Every field below is mandatory: a missing field fails the run instead of falling back to a default. Each service's own Vault paths are listed in its doc.

• key: {{ cs_project_code }}/certificate-authority/root-ca

{
    "root_ca_key_pem": "PEM-encoded Root CA private key",
    "root_ca_key_password": "Root CA private key password",
    "root_ca_cert_pem": "PEM-encoded Root CA certificate; signs every certificate issued during a run and is baked into every image's trust store",
    "domain": "Cluster domain"
}

• key: managed-services/smtp (platform-wide, not scoped under cs_project_code; read by SCM only)

{
    "smtpusername": "SMTP username",
    "smtppassword": "SMTP password",
    "fromaddress": "From address for outgoing mail",
    "smtphost": "SMTP host",
    "smtpport": "(int) SMTP port"
}

Localhost variables

Option	Type	Description	Default
ansible_connection	string	Ansible connection type	local
ansible_python_interpreter	string	Path to the Python interpreter for Ansible on local	./.venv/bin/python
ansible_host	string	The name/IP of the host to connect to for localhost	localhost

Global variables

These variables are defined in the all.vars section of inventory.yml or in group_vars/all/all.yml.

Every file inside group_vars/all/ applies to every host in the inventory: Ansible merges all of them for the all group regardless of filename. The filenames only organize variables by service; they do not scope a variable to hosts in the group of the same name.

The PyPI mirror and SCM application containers resolve DNS through 10.8.33.1 first, then 8.8.8.8 and 1.1.1.1. The first resolver is fixed in group_vars/all/all.yml, not read from Vault.

The root CA and SMTP values are read entirely from the two Vault secrets under Shared Vault configurations above; there's nothing to set for them here.

Option	Type	Description	Default
cs_project_code	string	Project code, the Vault bucket name	CS_PROJECT_CODE env variable (mandatory)
cs_env_debug	boolean	Enable debug logging	DEBUG env variable, else false
cs_no_log	boolean	Disable logging of sensitive tasks	true, unless cs_env_debug is true
ds_force_rotate_leaf_certs	boolean	Force every leaf private key, CSR, and certificate to regenerate on each run	true