diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..363d6f1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# 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 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/.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/` so history or return-code cues are accurate. diff --git a/README.md b/README.md index 79b28a8..2abbd1b 100644 --- a/README.md +++ b/README.md @@ -96,3 +96,18 @@ Um das Terminal etwas zu verschönern (und übersichtlicher zu machen) setze den ``` (vergiss auch hier die ``-Taste nicht...) +## Docker-Host vorbereiten +der Server benötigt einige Pakete, damit er seinen Dienst als Docker-Host antreten kann. +Zusätzliche Pakete sind nötig, damit die Hilfs-Scripte ordnungsgemäß laufen können. + +Von Hand würde man jetzt die [offizielle Docker.com Anleitung "Install Docker Engine on Debian"](https://docs.docker.com/engine/install/debian/) durchspielen. +Einfacher geht es, wenn schon jemand™ ein "ansible-playbook" hergestellt hat. Zufälligerweise liegt hier eins im Repo. +Ein Ansible-Playbook ist eine Datei, die für das Open-Source-Automatisierungs-Tool ansible einen Zustand eines Servers beschreibt. Ansible kümmert sich dann darum, diesen Zustand herzustellen. + +Um dieses Playbook zu verwenden benötigt man natürlich "ansible". + +ansible installieren und anschließend direkt alles aus ["Install Docker Engine on Debian"](https://docs.docker.com/engine/install/debian/) automatisch durchführen kannst du mit dem Skript `01-install-ansible-and-run-playbook.sh`. Wie gerade schon geübt machst du das mit dem Befehl +```sh +root@fobiX:~# bash scripts/01 +``` + diff --git a/ansible/install-docker.yml b/ansible/install-docker.yml new file mode 100644 index 0000000..b7ebbf2 --- /dev/null +++ b/ansible/install-docker.yml @@ -0,0 +1,8 @@ +- hosts: all + name: Dockerhost installieren + remote_user: root + gather_facts: yes + + roles: + - install_docker + diff --git a/ansible/roles/install_docker/tasks/main.yml b/ansible/roles/install_docker/tasks/main.yml new file mode 100644 index 0000000..28f00be --- /dev/null +++ b/ansible/roles/install_docker/tasks/main.yml @@ -0,0 +1,64 @@ +# --- +# tasks file for install_docker +- name: Check if Docker is installed + become: yes + command: docker -v + register: docker_installed + ignore_errors: true + +- name: Ensure no conflicting Docker packages are installed + become: yes + ansible.builtin.apt: + name: + - docker.io + - docker-doc + - docker-compose + - podman-docker + - containerd + - runc + state: absent + purge: yes + +- name: Install Docker + become: yes + block: + - name: Add Docker's official GPG key + block: + - name: Install necessary packages + become: yes + ansible.builtin.apt: + name: + - ca-certificates + - curl + - gnupg + state: latest + update_cache: yes + - name: Add GPG key + ansible.builtin.shell: + cmd: | + install -m 0755 -d /etc/apt/keyrings + curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc + chmod a+r /etc/apt/keyrings/docker.asc + - name: Add the repository to Apt sources + block: + - name: Add repos + ansible.builtin.shell: + cmd: | + echo \ + "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \ + "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + + - name: Install Docker packages + become: yes + ansible.builtin.apt: + name: + - docker-ce + - docker-ce-cli + - containerd.io + - docker-buildx-plugin + - docker-compose-plugin + state: latest + update_cache: yes + when: docker_installed.failed + diff --git a/scripts/01-install-ansible-and-run-playbook.sh b/scripts/01-install-ansible-and-run-playbook.sh new file mode 100644 index 0000000..2f09ccf --- /dev/null +++ b/scripts/01-install-ansible-and-run-playbook.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +cd "${REPO_ROOT}" + +if [[ ${EUID} -ne 0 ]]; then + echo "Bitte als root oder per sudo ausführen." >&2 + exit 1 +fi + +echo "[0/3] Arbeitsverzeichnis: ${REPO_ROOT}" + +echo "[1/3] apt-Index aktualisieren..." +apt-get update -y + +echo "[2/3] Ansible installieren..." +DEBIAN_FRONTEND=noninteractive apt-get install -y ansible + +echo "[3/3] Playbook ansible/install-docker.yml lokal ausführen..." +ansible-playbook \ + -i localhost, \ + --connection=local \ + ansible/install-docker.yml + +echo "Fertig: install-docker.yml wurde erfolgreich auf localhost angewendet."