138 lines
5.6 KiB
Markdown
138 lines
5.6 KiB
Markdown
# Getting Started
|
|
|
|
## Developer Setup
|
|
|
|
```bash
|
|
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](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases).
|
|
|
|
## 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
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` with your tokens:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```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 `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):
|
|
|
|
```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.
|