Controller and Secrets

Controller and Secrets

Local requirements

The project pins the development toolchain in pyproject.toml and .python-version:

• Python 3.12+
• ansible-core>=2.19,<3
• passlib>=1.7.4,<2
• pre-commit>=4,<5
• yamllint>=1.37,<2
• uv
• just for repository recipes
• a running Docker engine for lightweight tests

Install it once per clone:

uv sync --group dev
uv run pre-commit install
uv run pre-commit install --hook-type commit-msg

Ansible defaults

ansible.cfg uses inventories/production/hosts.yaml by default and searches roles in roles and roles/apps. SSH host-key verification is enabled.

The default connection settings are:

pipelining = True
retries = 3
timeout = 30

The project also sets SSH keepalives in group_vars/all.yaml:

ansible_ssh_common_args: "-o StrictHostKeyChecking=accept-new -o ServerAliveInterval=15 -o ServerAliveCountMax=4"

accept-new records a previously unknown host key, but rejects a changed known key. A changed key can mean a rebuilt server or a real security problem. Verify the server identity before deleting a known-host entry.

Vault file

The repository intentionally does not contain secrets. group_vars/vault.yaml, .vault_password, and .vault_password_file are ignored by Git.

Create an encrypted vault:

uv run ansible-vault create group_vars/vault.yaml

Edit it later:

uv run ansible-vault edit group_vars/vault.yaml

Run playbooks with one of these approaches:

# Prompt for the vault password.
uv run ansible-playbook --ask-vault-pass playbooks/bootstrap.yaml

# Or keep a local, ignored password file.
ANSIBLE_VAULT_PASSWORD_FILE=.vault_password \
  uv run ansible-playbook playbooks/bootstrap.yaml

Never commit .vault_password or a decrypted vault.yaml.

Required secret values

Variable	Needed by	Notes
vault_bootstrap_login_user_ssh_public_keys	Bootstrap	At least one usable public key.
vault_bootstrap_users_default_password	Bootstrap	Initial password only; it is not overwritten on later runs.
vault_bootstrap_users_password_salt	Bootstrap	Use random letters, digits, ., or /.
vault_traefik_acme_email	Traefik	Required for ACME certificate registration.
vault_traefik_dashboard_password	Traefik dashboard	Required only when dashboard is enabled.
vault_vaultwarden_admin_token	Vaultwarden	Required when Vaultwarden is configured.
vault_telemt_config	Telemt	Full TOML configuration, treated as secret.

Before every real deployment

git status --short
git diff --check
just check-worktree

Do not treat a green syntax check as a deployment approval. Confirm inventory, DNS, cloud firewall rules, and vault values separately.