poimen-memory/CI-SETUP.md

# CI/CD Setup — Registry Push Configuration

## One-Time Setup

The CI/CD pipeline automatically builds and pushes Docker images when you push to `main`.

### 1. Create or Get Registry Token

**Option A: Use Organization Token** (Recommended)
```bash
# Ask Rock for the existing 'rock' organization PAT
# It should already have write:package permissions
```

**Option B: Create Personal Token**
```bash
# In browser: https://git.riotpiao.com/user/settings/tokens
# 1. Click "Generate New Token"
# 2. Name: "Docker Registry"
# 3. Scope: Check `write:package`
# 4. Generate and copy the token
```

### 2. Add Repository Secret

Go to: **https://git.riotpiao.com/rock/poimen-memory/settings/secrets**

Add secret:
- **Name**: `REGISTRY_PAT`
- **Value**: `<token-from-step-1>`
- **Save**

### 3. Verify Setup

```bash
# Push a commit (any change will do)
cd ~/workplace/Poimen/memory
git commit --allow-empty -m "Trigger CI build"
git push origin main

# Check Actions tab
# https://git.riotpiao.com/rock/poimen-memory/actions
```

---

## How It Works

```
Push to main
    ↓
Forgejo Actions triggered
    ↓
Test:  cargo test --all
    ↓ (only if tests pass)
Build: docker build -t forgejo.riotpiao.com/rock/poimen-memory:latest .
    ↓
Push:  docker push (using REGISTRY_PAT secret)
    ↓
ArgoCD detects new image
    ↓
Auto-deploy to poimen namespace
```

---

## Check Status

**Web UI** — See build progress:
```
https://git.riotpiao.com/rock/poimen-memory/actions
```

**CLI** — Watch deployment:
```bash
kubectl get application -n argocd poimen-memory-app -w
kubectl get pods -n poimen -l app.kubernetes.io/name=poimen-memory -w
```

**Verify Image** — Check registry:
```bash
docker pull forgejo.riotpiao.com/rock/poimen-memory:latest
```

---

## Once Image is Ready

```bash
# Port forward to local
kubectl port-forward -n poimen svc/poimen-memory 8080:80 &

# Test
curl http://localhost:8080/health
```

---

## Troubleshooting

### Secret Not Found Error
- Go to: https://git.riotpiao.com/rock/poimen-memory/settings/secrets
- Verify `REGISTRY_PAT` is set

### Login Failed
- Token might be expired or revoked
- Create a new token and update the secret

### Build Failed
- Check Actions logs for the error
- Usually: tests failed
- Fix locally: `cargo test --all`

### Image Exists But Pods Not Running
- Check pod events: `kubectl describe pod -n poimen <pod-name>`
- Usually: image pull policy issue or pod crashed
- Check logs: `kubectl logs -n poimen deployment/poimen-memory`

---

## Apply to Other Repos

The same setup works for all Poimen repos:

```bash
# For poimen, poimen-workflows, etc:
# 1. Create .forgejo/workflows/build.yaml (copy from template below)
# 2. Add REGISTRY_PAT secret
# 3. Push and watch it deploy
```

**Template**: See `.forgejo/workflows/TEMPLATE.md` in this repo

---

## Pattern Overview

**Based on**: homelab-frontend (proven production pattern)
- Uses `REGISTRY_PAT` secret ✓
- Docker login + push ✓
- Tags: commit SHA + latest ✓
- ArgoCD watches tags ✓

**Consistency**: All Poimen repos use same pattern
- Same secret name: `REGISTRY_PAT`
- Same workflow structure
- Same deployment process