agent-helm/deploy/DEPLOY.md

Deploy: agent-helm på Pi5 via Gitea Actions → registry → Dockge → NPM

Flödet: git push master → Gitea Actions-runnern på Pi5 bygger arm64-image:n → pushar till localhost:5000/agent-helm-server:latest → Dockge kör stacken → NPM exponerar https://rcai.brasse-pc.eu. Uppdatering = push + klicka Update i Dockge.

push master ──► gitea-act-runner (bygg arm64) ──► localhost:5000/agent-helm-server:latest
                                                          │
                                                   Dockge: Update (pull + up -d)
                                                          ▼
                                          container "agent-helm" :8787 (srv_default)
                                                          ▲
                                  NPM: rcai.brasse-pc.eu ─┘ (Websockets ON, TLS)

Förutsättningar som redan är på plats: DNS rcai.brasse-pc.eu → 155.4.72.51 (✓), srv_default-nätet, docker-registry och npm körs (✓). Gitea 1.24 har Actions påslaget som default.

Kataloger & ägarskap (gör FÖRE deploy)

Bind-mountade kataloger måste finnas och ägas av uid 1000 innan containern startar. Startar containern först skapar Docker katalogen som root, och appen (kör som uid 1000 node) kan då inte läsa/skriva den. Skapa som brasse (= uid 1000):

# data/config för appen (måste vara uid 1000-ägd — appen skriver hit)
mkdir -p /srv/docker/agent-helm
# runner-state
mkdir -p /srv/docker/act-runner
# stack-mappar för Dockge
mkdir -p /srv/dockge-staks/act-runner /srv/dockge-staks/agent-helm

# verifiera ägarskap (ska visa uid 1000 i andra kolumnen)
ls -ln /srv/docker | grep -E 'agent-helm|act-runner'

Om någon katalog råkat bli root-ägd (t.ex. för att en container startade först):

sudo chown -R 1000:1000 /srv/docker/agent-helm
# starta sedan om stacken så mounten läses om

---

Steg 1 — Registrera Gitea Actions-runnern (engång)

1. Hämta registrerings-token i Gitea: Site Administration → Actions → Runners → Create new runner → kopiera token. (Eller repo-nivå: brasse/agent-helm → Settings → Actions → Runners.)

2. Skapa stacken i Dockge (dockge.brasse-pc.eu):

   • Ny stack, namn act-runner.
   • Klistra in deploy/act-runner.compose.yaml.
   • Lägg deploy/act-runner.config.yaml som filen config.yaml i stacken (Dockge låter dig skapa extra filer i stack-mappen, dvs /srv/dockge-staks/act-runner/config.yaml).
   • I stackens env: GITEA_RUNNER_REGISTRATION_TOKEN=<din-token>.
   • Deploy.

3. Verifiera: i Gitea Site Administration → Actions → Runners ska pi5-docker-runner dyka upp som Idle. Loggen: docker logs gitea-act-runner.

Runnern monterar värdens docker.sock och bygger med Pi5:ans egen Docker → arm64 nativt, och localhost:5000 (registryn) trustas automatiskt.

---

Steg 2 — Första bygget

.gitea/workflows/build.yaml triggas på push till master/main. Trigga det:

• Pusha en commit till master, eller
• Gitea repo → Actions → välj workflowen → Run workflow (manuell dispatch).

Följ körningen under repo:ts Actions-flik. När den är grön finns localhost:5000/agent-helm-server:latest i registryn.

Snabbkoll (på Pi5, eller via claude-docker):

curl -s http://localhost:5000/v2/agent-helm-server/tags/list
# -> {"name":"agent-helm-server","tags":["latest","<sha>"]}

---

Steg 3 — Kör stacken i Dockge

1. Skapa host-katalogen för config/data (som brasse, uid 1000): mkdir -p /srv/docker/agent-helm Den bind-mountas till /app/data i containern (där framtida db/auth hamnar); containern kör som uid 1000 = brasse så filerna blir korrekt ägda.
2. Ny stack i Dockge, namn agent-helm.
3. Klistra in deploy/agent-helm.compose.yaml.
4. I stackens env: AGENT_HELM_TOKEN=<lång-slumpad-hemlighet> (generera t.ex. openssl rand -hex 32).
5. Deploy. Kolla i Dockge att containern agent-helm är running.

---

Steg 4 — NPM proxy host (manuellt i NPM-UI:t)

I Proxy.brasse-pc.eu → Proxy Hosts → Add Proxy Host:

Fält	Värde
Domain Names	rcai.brasse-pc.eu
Scheme	http
Forward Hostname	agent-helm
Forward Port	8787
Websockets Support	PÅ (viktigt — WS-kanalen)
Block Common Exploits	valfritt

Under SSL: Request a new SSL Certificate (Let's Encrypt) + Force SSL + HTTP/2.

Spara. Öppna https://rcai.brasse-pc.eu → logga in med AGENT_HELM_TOKEN.

---

Steg 5 — Anslut en daemon (annars finns inga sessioner)

Servern är bara control-plane. En daemon kör agenten och ansluter till servern. Kör den var du vill (workstation, eller som egen container senare):

# på workstationen, i agent-helm-repot
AGENT_HELM_TOKEN=<samma-token> \
SERVER_URL=wss://rcai.brasse-pc.eu \
AGENT_CMD=gemini \
pnpm dev:daemon

Daemonen dyker upp som en session i web-UI:t. (Kräver att NPM:s Websockets är på.)

---

Klienten (daemon) — installera på en Linux-maskin

Klienten distribueras som självständiga binärer (Node + node-pty inbäddat, inga beroenden på målet) för linux-x64 och linux-arm64, byggda av .gitea/workflows/release.yaml och publicerade som Release-assets på Gitea.

Skapa en release (bygger båda arkitekturerna på Pi-runnern):

git tag v0.1.0 && git push origin v0.1.0
# eller: Gitea -> Actions -> release-client -> Run workflow (ange tag)

Installera på valfri Linux-maskin (Arch, Ubuntu, …) — ett kommando:

curl -fsSL https://gitea.brasse-pc.eu/brasse/agent-helm/raw/branch/main/install.sh | sh

Installern detekterar arch, hämtar rätt binär från senaste releasen, lägger agent-helm i /usr/local/bin (eller ~/.local/bin), skapar ~/.config/agent-helm/config.env och en (valfri) systemd-user-service.

Sätt token + kör:

${EDITOR:-nano} ~/.config/agent-helm/config.env     # AGENT_HELM_TOKEN, SERVER_URL, AGENT_CMD
systemctl --user daemon-reload && systemctl --user enable --now agent-helm
# eller direkt:  set -a; . ~/.config/agent-helm/config.env; agent-helm

Klienten ansluter till wss://rcai.brasse-pc.eu och dyker upp som en session i UI:t.

Uppdatera till senaste

1. git push master → runnern bygger + pushar :latest.
2. Dockge → stacken agent-helm → Update (kör docker compose pull && up -d).

Det var det — senaste image:n körs.

---

Felsökning

Symptom	Trolig orsak / åtgärd
Runnern syns inte i Gitea	Fel/förbrukad token. Skapa ny, uppdatera env, redeploy act-runner.
Workflow fastnar på actions/checkout	Runnern når inte github för att hämta action:en, eller inte gitea-d:3000. Kolla att runnern är på srv_default.
docker: command not found i jobbet	Fel job-image. Labeln ska peka på catthehacker/ubuntu:act-latest.
push nekas / http: server gave HTTP response to HTTPS client	Pusha till localhost:5000 (inte 192.168.0.19:5000) från Pi-runnern — localhost trustas som insecure automatiskt.
rcai ger 502	agent-helm-containern nere, eller fel forward-namn/port i NPM.
WS ansluter inte (UI loggar in men sessioner laddar ej)	Websockets Support av i NPM-hosten. Slå på.
Bygget kompilerar node-pty och failar	Ska inte hända — Dockerfilen filtrerar bort daemon. Om det sker: kontrollera --filter-raderna.