diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md new file mode 100644 index 0000000..7b3e834 --- /dev/null +++ b/docs/RUNBOOK.md @@ -0,0 +1,62 @@ +# Runbook + +This runbook explains how to execute and maintain the scripts in this repository. + +## Execution Model + +Most scripts can be executed directly with Bash: + +```bash +bash scripts/script_name.sh --help +``` + +For production usage, prefer absolute paths and explicit options: + +```bash +/usr/bin/bash /opt/devops/scripts/system_health_report.sh --output /var/tmp/health.txt +``` + +## Logging + +Scripts print timestamped messages to standard output and standard error. +When running through cron or a scheduler, redirect output to a dedicated log file: + +```bash +bash scripts/docker_cleanup.sh --dry-run >> /var/log/docker-cleanup.log 2>&1 +``` + +## Permissions + +Some scripts require elevated privileges: + +- Docker maintenance requires access to the Docker daemon. +- User bootstrap usually requires root. +- Reading system services may require systemd access. +- Writing into deployment paths may require ownership or sudo. + +Avoid running scripts as root unless the operation requires it. + +## Safety Checklist + +Before scheduling or automating a script: + +1. Confirm the script exits non-zero on failure. +2. Confirm the script handles missing dependencies. +3. Confirm retention settings are aligned with business needs. +4. Confirm secrets are supplied through secure environment variables or secret stores. +5. Confirm logs do not expose passwords, tokens, or private keys. + +## Suggested CI Validation + +At minimum, run: + +```bash +bash tests/syntax_check.sh +``` + +If ShellCheck is available: + +```bash +shellcheck scripts/*.sh tests/*.sh +``` +