55 lines
1.8 KiB
Markdown
55 lines
1.8 KiB
Markdown
# 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
|
|
|
|
1. Create a new role in `ansible/roles/<service>/`.
|
|
2. Add it to the proxy or IDP play in `ansible/playbooks/setup.yml` with a
|
|
`tags: [<service>]` annotation.
|
|
3. 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:
|
|
|
|
```bash
|
|
# 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.
|