GRM-36: feat: implement documentation-as-code with wiki sync and doc-coverage

Add /docs/ directory with user and technical documentation extracted from README, AGENTS.md, and source code. Add scripts/sync_wiki.py to sync docs to Gitea wiki via API. Add scripts/doc_coverage.py to check CLI commands, modules, and CI scripts are documented. Add sync-wiki.yml workflow for auto-sync on merge and release. Slim down README.md to lean entry point. 28 new unit tests, 100% coverage maintained. Closes GRM-36
2026-06-21 19:45:34 +00:00
parent 7fe85423b4
commit 5b05db4e6d
21 changed files with 1899 additions and 415 deletions
@@ -0,0 +1,88 @@
+# Getting Started
+
+## Developer Setup
+
+```bash
+git clone https://git.oblachno.oblachno.com/oblachno/gitea-runner-manager.git
+cd gitea-runner-manager
+pyenv install 3.12
+pyenv local 3.12
+make setup
+```
+
+## Configure Gitea Credentials
+
+```bash
+cp .env.example .env
+# Edit .env:
+# GITEA_URL=https://git.example.com
+# GITEA_REGISTRATION_TOKEN=your-registration-token
+```
+
+`GITEA_REGISTRATION_TOKEN` is the runner registration token obtained from your Gitea instance (Admin → Actions → Runners → Create Registration Token).
+
+### Admin API Token (optional)
+
+Set `GITEA_ADMIN_TOKEN` to enable informational API checks during integration test. This is **optional** — the test primarily verifies the runner by checking:
+
+1. **`.runner` registration file** exists and contains valid JSON (proves successful registration)
+2. **Systemd user service** is active (proves daemon is polling for jobs)
+
+API checks, if enabled, are purely informational and do not affect pass/fail.
+
+## Install a Runner
+
+Using the CLI (you will be prompted for the sudo password by default):
+
+```bash
+grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner
+```
+
+> **Automation tip:** Configure passwordless sudo on the remote host and pass `--no-ask-become-pass` to skip the password prompt. This is recommended for CI/CD pipelines.
+
+Using Make:
+
+```bash
+make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner
+```
+
+## Verify Runner
+
+The installer performs an automated integration test that verifies:
+
+1. **`.runner` file exists** with valid JSON containing `id`, `uuid`, `token`, `address` — this proves successful registration with Gitea
+2. **Systemd user service is active** — this proves the daemon is polling for jobs
+
+You can also check the Gitea UI under **Actions → Runners** to confirm the runner appears as **Online**.
+
+Optional: If `GITEA_ADMIN_TOKEN` is set, the installer will also query the Gitea API and report whether the runner appears in the admin or repo runners list. This is purely informational.
+
+## View Logs
+
+**GRM application logs** (Python CLI output):
+
+```bash
+# Application log file (all messages including DEBUG)
+cat ~/.local/state/grm/logs/grm.log
+
+# Enable debug logging in the current session
+GRM_LOG_LEVEL=DEBUG grm install 192.168.1.10 --user ubuntu --name prod-runner
+```
+
+**Runner logs** (on the remote host):
+
+```bash
+# Runner logs (via systemd user service)
+sudo -u grm-<name> journalctl --user -u gitea-runner -f
+```
+
+The GRM application writes to two destinations:
+
+| Destination | Level | Content |
+|-------------|-------|---------|
+| Console (stdout) | `GRM_LOG_LEVEL` (default: INFO) | Colorised user-facing messages and operation reports |
+| `~/.local/state/grm/logs/grm.log` | DEBUG | All messages with timestamps and severity |
+
+Set `GRM_LOG_LEVEL` to one of `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL` to control console verbosity. The log file always captures everything at DEBUG level regardless of the console setting.
+
+Console output is automatically colorised via ``click.echo``: operation headers in bright cyan, completed steps in green, failures in red, and status updates in yellow.