2.7 KiB
Repository Guidelines
Project Structure & Module Organization
Infrastructure automation lives in ansible/ with playbooks like install-docker.yml and roles under ansible/roles/ (install_docker, install_oh-my-zsh, mailcow-ansiblerole). Reusable helper prompts for shell sessions sit in prompts/, while ready-made walkthrough scripts belong in scripts/ (for example 00-Beispiel-1.sh). The root README.md is the canonical handout for trainees, so update it alongside any major workflow change.
Build, Test, and Development Commands
Use ansible-playbook -i <inventory> ansible/install-docker.yml to provision a host end-to-end. Validate changes quickly with ansible-playbook --syntax-check ansible/install-docker.yml and dry-run with ansible-playbook --check ... before touching real servers. Scripted exercises run via bash scripts/00-Beispiel-1.sh, which is also a template for new labs. After editing shell utilities, run bash -n scripts/<file>.sh to catch syntax errors.
Coding Style & Naming Conventions
YAML uses two-space indents, lowercase keys, and descriptive role/variable names (install_docker, with_starship). Keep playbooks idempotent and prefer Ansible modules over raw shell. Shell scripts target Debian-based hosts; start with #!/usr/bin/env bash, set set -euo pipefail, and use lowercase, hyphenated filenames. Any visible output should be concise so trainees can follow along live.
Testing Guidelines
Every role change must pass ansible-playbook --syntax-check and a --check run against a disposable host. When roles install packages, assert outcomes with changed_when/failed_when to keep reports accurate. For scripts, add usage comments at the top, run them in a throwaway VM, and document expected prompts or side effects inside the script itself.
Commit & Pull Request Guidelines
Follow the existing concise, German-friendly summaries (README.md aktualisiert, kleine korrekturen). Start messages with an imperative verb and keep the subject ≤70 chars; add detail in the body when configuration files or roles change. Pull requests should describe the scenario (host type, inventory snippet, or script name), list verification commands, and attach screenshots/log excerpts when UI or prompt adjustments are involved. Link training issues or agenda items so reviewers know which exercise the change supports.
Security & Configuration Tips
Assume root SSH on wildcard hosts (fobiX.benbex.de); never store credentials in the repo. Before running provisioning playbooks, confirm the target number (X) and ensure DNS wildcard records resolve locally. When sharing prompt tweaks, reference the exact file in prompts/ and remind users to source it with . prompts/<name> so history or return-code cues are accurate.