managarten/docs/MAC_MINI_RUNNER_SETUP.md

Mac Mini Setup: GitHub Actions Runner & SSH-Zugang

Diese Anleitung auf dem Mac Mini ausführen.

---

Teil A: SSH-Zugang einrichten

Damit von Entwicklungsrechnern (und Claude Code) direkt per SSH auf den Mac Mini zugegriffen werden kann.

A1. SSH-Dienst aktivieren (falls noch nicht aktiv)

# Prüfen ob SSH aktiv ist
sudo systemsetup -getremotelogin

# Falls "Off": aktivieren
sudo systemsetup -setremotelogin on

A2. SSH-Key hinterlegen

Folgenden Public Key in ~/.ssh/authorized_keys auf dem Mac Mini einfügen:

mkdir -p ~/.ssh && chmod 700 ~/.ssh

# Claude Code SSH-Key hinzufügen
echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmtp92RmE6lPhHRg24VSYIvq9ne4+qe61SiR4c+lPWu claude-code@manacore" >> ~/.ssh/authorized_keys

chmod 600 ~/.ssh/authorized_keys

A3. Verbindung testen (vom Entwicklungsrechner)

ssh till@192.168.178.131 "echo 'SSH works!'"

A4. SSH-Config auf dem Entwicklungsrechner

Falls noch nicht vorhanden, ~/.ssh/config erstellen/ergänzen:

# Lokales Netzwerk (direkt)
Host mana-server
    HostName 192.168.178.131
    User till

# Über Cloudflare Tunnel (von extern)
Host mana-server-remote
    HostName mac-mini.mana.how
    User till
    ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h

A5. Nützliche SSH-Befehle

# Verbinden
ssh mana-server

# Direkt einen Befehl ausführen
ssh mana-server "cd ~/projects/manacore-monorepo && ./scripts/mac-mini/status.sh"

# Manuelles Deployment
ssh mana-server "cd ~/projects/manacore-monorepo && git pull && docker compose -f docker-compose.macmini.yml --env-file .env.macmini up -d --build matrix-web"

# Logs eines Containers ansehen
ssh mana-server "docker logs -f mana-matrix-web --tail 50"

---

Teil B: GitHub Actions Self-Hosted Runner

1. Runner-Token holen

1. Gehe zu: https://github.com/Memo-2023/manacore-monorepo/settings/actions/runners/new
2. Wähle macOS und ARM64
3. Kopiere den Token aus dem --token Parameter (sieht so aus: AXXXX...)

2. Runner installieren

# Verzeichnis erstellen
mkdir -p ~/actions-runner && cd ~/actions-runner

# Runner herunterladen (ARM64 macOS)
curl -o actions-runner.tar.gz -L https://github.com/actions/runner/releases/latest/download/actions-runner-osx-arm64-2.322.0.tar.gz

# Entpacken
tar xzf actions-runner.tar.gz

# Konfigurieren (Token von Schritt 1 einsetzen)
./config.sh --url https://github.com/Memo-2023/manacore-monorepo --token DEIN_TOKEN_HIER

# Bei den Prompts:
#   Runner group: [Enter] (default)
#   Runner name:  mac-mini
#   Labels:       [Enter] (default: self-hosted,macOS,ARM64)
#   Work folder:  [Enter] (default: _work)

3. Als LaunchAgent einrichten (Autostart)

# Installiert den LaunchAgent automatisch
cd ~/actions-runner
./svc.sh install

# Starten
./svc.sh start

# Status prüfen
./svc.sh status

4. Prüfen ob es läuft

# Lokal prüfen
./svc.sh status

# Oder im Browser:
# https://github.com/Memo-2023/manacore-monorepo/settings/actions/runners
# → Runner "mac-mini" sollte als "Idle" angezeigt werden

5. Docker-Zugriff sicherstellen

Der Runner braucht Zugriff auf Docker:

# Prüfen ob Docker läuft
docker info

# Prüfen ob docker compose funktioniert
docker compose version

# Prüfen ob das Projekt-Verzeichnis existiert
ls ~/projects/manacore-monorepo/docker-compose.macmini.yml

6. Test-Deployment auslösen

Entweder:

• Push auf main machen (deployt automatisch geänderte Services)
• Oder manuell: https://github.com/Memo-2023/manacore-monorepo/actions/workflows/cd-macmini.yml → "Run workflow" → Service wählen

Fehlerbehebung

Runner ist offline

cd ~/actions-runner
./svc.sh status
./svc.sh stop
./svc.sh start

Runner-Token abgelaufen

cd ~/actions-runner
./svc.sh stop
./config.sh remove --token ALTES_TOKEN
# Neuen Token holen (siehe Schritt 1)
./config.sh --url https://github.com/Memo-2023/manacore-monorepo --token NEUES_TOKEN
./svc.sh start

Logs ansehen

# Runner-Logs
tail -f ~/actions-runner/_diag/Runner_*.log

# Workflow-Logs: im GitHub UI unter Actions-Tab

Was passiert nach dem Setup?

Bei jedem Push auf main:

1. Der Runner erkennt welche Services sich geändert haben
2. Pullt den neuesten Code (git pull)
3. Baut nur die geänderten Docker-Container neu (docker compose up -d --build <service>)
4. Führt Health Checks durch
5. Ergebnis ist im GitHub Actions-Tab sichtbar

Manuelle Deploys sind jederzeit möglich über den "Run workflow" Button im Actions-Tab.