grm/docs/user/getting-started.md

Getting Started

Developer Setup

git clone https://git.oblachno.oblachno.fyi/oblachno-oss/grm.git
cd grm
git checkout $(git describe --tags --abbrev=0)  # Checkout latest stable release
pyenv install 3.12
pyenv local 3.12
make setup

Important: Always checkout the latest release tag before running make setup. The master branch may contain unreleased changes that are not yet stable. The git describe --tags --abbrev=0 command automatically selects the most recent tagged release. To see all available releases, run git tag --sort=-version:refname or check the releases page.

Configure Gitea Credentials

GRM needs two tokens from your Gitea instance: a registration token (required) and an admin API token (optional, for post-install verification).

Step 1: Get the Registration Token

The registration token tells Gitea to accept the runner when it connects.

1. Log in to your Gitea instance as an administrator
2. Navigate to Site Administration → Actions → Runners
3. Click Create Registration Token
4. Copy the token — it starts with GR

Note: There are three levels of registration tokens:

• Instance-level (Site Administration → Actions → Runners) — registers a runner for all repositories
• Organization-level (Organization → Settings → Actions → Runners) — registers a runner for repos in that organization
• Repository-level (Repository → Settings → Actions → Runners) — registers a runner for a single repository

Use instance-level tokens for shared runners, and repo-level tokens for dedicated runners.

Step 2: Get the Admin API Token (optional)

The admin API token enables post-install API checks that verify the runner appears in Gitea's runner list. This is purely informational — the integration 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)

To get an admin API token:

1. Go to Settings → Applications → Generate New Token
2. Give it a name (e.g., "GRM Install Verification")
3. Select the admin scope (or at minimum: read:user, read:repository, read:admin)
4. Click Generate Token and copy it immediately (it won't be shown again)

Step 3: Create the .env File

cp .env.example .env

Edit .env with your tokens:

# Your Gitea instance URL
GITEA_URL=https://git.example.com

# Registration token from Step 1
GITEA_REGISTRATION_TOKEN=GRxxxxxxxxxxxxxxxxxx

# Admin API token from Step 2 (optional)
REPO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Environment Variables Reference

Variable	Required	Description
GITEA_URL	Yes	Gitea instance URL (e.g., https://git.example.com)
GITEA_REGISTRATION_TOKEN	Yes	Runner registration token from Gitea admin panel
REPO_TOKEN	No	Admin API token for post-install verification
GITEA_INTEGRATION_RETRIES	No	API check retries (default: 3)
GITEA_RUNNER_USER	No	Default SSH user (overrides --user)
GITEA_RUNNER_KEY	No	Default SSH key path (overrides --key)
GITEA_RUNNER_LABELS	No	Default runner labels (overrides --labels)
GRM_LANG	No	UI language: en, bg, de, ru, zh (default: en)

Install a Runner

Using the CLI (you will be prompted for the sudo password by default):

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:

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 REPO_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):

# 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):

# 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.