emil
5b05db4e6d
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
56 lines
2.1 KiB
Markdown
56 lines
2.1 KiB
Markdown
# Installation
|
|
|
|
## Prerequisites
|
|
|
|
- **SSH key authentication** — The remote host must be reachable via SSH using the user specified with `--user` and the private key specified with `--key`. GRM uses Ansible under the hood, which connects to the target host over SSH to execute all installation and configuration tasks. Without valid SSH credentials, Ansible cannot establish a connection and the deployment will fail.
|
|
- **Sudo access** — GRM requires root privileges on the remote host to create system users, install packages, and configure rootless Docker. By default, you will be prompted interactively for the sudo password. For automation or uninterrupted workflows, configure passwordless sudo on the remote host and pass `--no-ask-become-pass`.
|
|
|
|
## Supported Operating Systems
|
|
|
|
- Arch Linux
|
|
- Ubuntu 22.04 / 24.04
|
|
- Debian 12
|
|
|
|
All supported OSes are tested in CI via molecule scenarios on every PR.
|
|
|
|
## Quick Start Install
|
|
|
|
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.
|
|
|
|
## Make Install
|
|
|
|
Using Make:
|
|
|
|
```bash
|
|
make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner
|
|
```
|
|
|
|
## Runner Registry
|
|
|
|
After installation, GRM stores each runner's connection details (host, user, SSH key, Gitea URL) in a local JSON registry at `~/.local/share/grm/runners.json`. This means you rarely need to repeat connection arguments:
|
|
|
|
```bash
|
|
# List all registered runners with live systemd status
|
|
grm list
|
|
```
|
|
|
|
## Multiple Instances on the Same Host
|
|
|
|
Each runner instance is fully isolated with its own system user, rootless Docker daemon, data directory, and systemd user service:
|
|
|
|
```bash
|
|
# Install two runners on the same host
|
|
grm install 192.168.1.10 --user ubuntu --name workflow-runner
|
|
grm install 192.168.1.10 --user ubuntu --name build-runner
|
|
|
|
# Manage them independently by name
|
|
grm stop workflow-runner
|
|
grm status build-runner
|
|
```
|