19 lines
2.7 KiB
Markdown
19 lines
2.7 KiB
Markdown
# 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.
|