Contributing

Code style

YAML files use 4-space indentation, formatted with yamlfix.
Jinja2 templates use the file extension .j2.
Role names use snake_case (e.g., docker_registry).
Task names are human-readable sentences (e.g., "Ensure SSL private keys are readable by containers").

Role structure

Each role follows the standard Ansible layout:

roles/<name>/
├── defaults/main.yml    # Default variables
├── tasks/
│   ├── main.yml         # Entry point
│   └── *.yml            # Additional task files (deploy, restore, etc.)
├── templates/           # Jinja2 templates (.j2)
├── files/               # Static files
└── meta/main.yml        # Role dependencies

Adding a new service

Create a new role in ansible/roles/<service>/.
Add it to the proxy or IDP play in ansible/playbooks/setup.yml with a tags: [<service>] annotation.
If the role depends on docker or apache, those roles handle themselves internally — just declare the dependency in meta/main.yml.

Testing changes

Always test locally before deploying to production:

# Run against local VMs
pipenv run ansible-playbook -i ansible/inventories/debug/hosts.ini ansible/playbooks/setup.yml \
    --tags <service>

Committing

Keep commits focused: one logical change per commit.
Use conventional-ish commit messages:
- feat: add offline email notifications to prosody
- fix: correct registry vhost name collision
- chore: migrate collection roles to local roles/

Vault changes

When adding new secrets, add them to the vault file and document the variable name (but not the value) somewhere discoverable — either in the role's defaults/main.yml as a commented placeholder or in the playbook next to the role invocation.

1.8 KiB Raw Blame History