Standardize CI/CD: use homelab-frontend pattern (REGISTRY_PAT, docker:27-cli, all repos)

.forgejo/workflows/TEMPLATE.md

@@ -0,0 +1,156 @@
+# CI/CD Workflow Template for Poimen Repos
+
+## Pattern Used by Homelab-Frontend
+
+**File**: `.gitea/workflows/build-prod.yaml` (equivalent: `.forgejo/workflows/build.yaml`)
+
+### Key Components
+
+```yaml
+jobs:
+  build:
+    runs-on: golang  # or rust, or docker
+    container:
+      image: docker:27-cli
+      volumes:
+        - /docker-certs/client:/docker-certs/client:ro
+    env:
+      DOCKER_HOST: tcp://localhost:2376
+      DOCKER_TLS_VERIFY: "1"
+      DOCKER_CERT_PATH: /docker-certs/client
+    steps:
+      - name: Registry login
+        run: |
+          echo "${REGISTRY_PAT}" | docker login "${REGISTRY}" \
+            --username rock --password-stdin
+        env:
+          REGISTRY_PAT: ${{ secrets.REGISTRY_PAT }}
+      
+      - name: Build
+        run: docker build -t "${IMAGE}:latest" .
+      
+      - name: Push
+        run: docker push "${IMAGE}:latest"
+```
+
+---
+
+## How to Apply to Any Poimen Repo
+
+### Step 1: Create Personal Access Token
+
+```bash
+# In browser: https://git.riotpiao.com/user/settings/tokens
+# Or use the existing 'rock' PAT for the organization
+```
+
+### Step 2: Set Repository Secret
+
+Go to **`https://git.riotpiao.com/rock/<repo>/settings/secrets`**
+
+Add secret:
+- **Name**: `REGISTRY_PAT`
+- **Value**: `<token-from-step-1>`
+
+### Step 3: Create Workflow File
+
+Copy this to `.forgejo/workflows/build.yaml`:
+
+```yaml
+name: Build and Push
+
+on:
+  push:
+    branches: [main]
+
+env:
+  REGISTRY: forgejo.riotpiao.com
+  IMAGE_NAME: rock/<your-repo-name>
+
+jobs:
+  test:
+    runs-on: rust  # or golang, or docker
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests
+        run: cargo test --all  # adjust for your language
+
+  build:
+    runs-on: golang
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    container:
+      image: docker:27-cli
+      volumes:
+        - /docker-certs/client:/docker-certs/client:ro
+    env:
+      DOCKER_HOST: tcp://localhost:2376
+      DOCKER_TLS_VERIFY: "1"
+      DOCKER_CERT_PATH: /docker-certs/client
+    steps:
+      - name: install node (required by JS-based actions)
+        run: apk add --no-cache nodejs git
+      
+      - uses: actions/checkout@v4
+      
+      - name: Registry login
+        run: |
+          echo "${REGISTRY_PAT}" | docker login "${REGISTRY}" \
+            --username rock --password-stdin
+        env:
+          REGISTRY_PAT: ${{ secrets.REGISTRY_PAT }}
+      
+      - name: Build
+        run: |
+          docker build \
+            -t "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest" \
+            -t "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}" \
+            .
+      
+      - name: Push
+        run: |
+          docker push "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest"
+          docker push "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}"
+```
+
+---
+
+## Apply to Poimen Repos
+
+### poimen-memory ✅ (current)
+- Status: Uses `FORGEJO_TOKEN` (built-in)
+- Can upgrade to `REGISTRY_PAT` pattern
+
+### poimen (orchestrator)
+- If has Dockerfile: add workflow
+- If K8s-only: validate with `yamllint` + `kustomize`
+
+### poimen-workflows
+- If has Docker: add workflow
+- Otherwise: validate YAML only
+
+### Pattern for All Repos
+
+```
+.forgejo/workflows/
+├── build.yaml           # For repos with Dockerfile
+├── validate.yaml        # For K8s-only repos (like homelab)
+```
+
+---
+
+## Summary
+
+**Established Pattern**:
+1. `REGISTRY_PAT` secret in repo
+2. `docker login` → `docker build` → `docker push`
+3. Image tagged: `latest` + commit SHA
+4. ArgoCD watches and auto-deploys
+
+**Once set up once**: 
+- Every push triggers build
+- Image auto-pushes to registry
+- ArgoCD syncs automatically
+- Zero manual intervention
+
+**Effort**: ~5 minutes per repo (token + secret + workflow file)

.forgejo/workflows/build.yaml

@@ -8,7 +8,7 @@ on:
 
 env:
   REGISTRY: forgejo.riotpiao.com
-  IMAGE_NAME: rock/poimen-memory
+  IMAGE: forgejo.riotpiao.com/rock/poimen-memory
 
 jobs:
   test:
@@ -17,39 +17,49 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       
-      - name: Run cargo build
+      - name: Run tests
-        run: cargo build --workspace
-      
-      - name: Run cargo test
         run: cargo test --all
 
-  build-image:
+  build:
-    name: Build and Push Image
+    name: Build and push image
-    runs-on: rust
+    runs-on: golang
     needs: test
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    container:
+      image: docker:27-cli
+      volumes:
+        - /docker-certs/client:/docker-certs/client:ro
+    env:
+      DOCKER_HOST: tcp://localhost:2376
+      DOCKER_TLS_VERIFY: "1"
+      DOCKER_CERT_PATH: /docker-certs/client
     steps:
+      - name: install node (required by JS-based actions)
+        run: apk add --no-cache nodejs git
+
       - uses: actions/checkout@v4
 
-      - name: Build Docker image
+      - name: Get short SHA
+        id: sha
+        run: |
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          echo "short_sha=${SHORT_SHA}" >> $GITHUB_OUTPUT
+
+      - name: Registry login
+        run: |
+          echo "${REGISTRY_PAT}" | docker login "${REGISTRY}" \
+            --username rock --password-stdin
+        env:
+          REGISTRY_PAT: ${{ secrets.REGISTRY_PAT }}
+
+      - name: Build
         run: |
           docker build \
-            -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest \
+            -t "${IMAGE}:${{ steps.sha.outputs.short_sha }}" \
-            -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
+            -t "${IMAGE}:latest" \
-            -f Dockerfile .
+            .
 
-          echo "Built images:"
+      - name: Push
-          docker images | grep "${{ env.IMAGE_NAME }}"
-      
-      - name: Login to registry and push
         run: |
-          # Use Forgejo's actor token which has registry access
+          docker push "${IMAGE}:${{ steps.sha.outputs.short_sha }}"
-          echo "${{ secrets.FORGEJO_TOKEN }}" | docker login ${{ env.REGISTRY }} \
+          docker push "${IMAGE}:latest"
-            -u ${{ github.actor }} --password-stdin
-          
-          docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
-          docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
-          
-          echo "Image pushed: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest"
-        env:
-          FORGEJO_TOKEN: ${{ secrets.FORGEJO_TOKEN }}

CI-FOR-ALL-POIMEN-REPOS.md

@@ -0,0 +1,224 @@
+# CI/CD for All Poimen Repos — Standardized Pattern
+
+## Overview
+
+All Poimen repos should follow the same CI/CD pattern for consistency and maintainability.
+
+**Pattern**: Test locally → Build image → Push to registry → ArgoCD deploys
+
+**Based on**: homelab-frontend (proven production pattern)
+
+---
+
+## Repos & Status
+
+### Repos That Need Docker Deployment
+
+| Repo | Status | Dockerfile | Notes |
+|------|--------|-----------|-------|
+| **poimen-memory** | ✅ Ready | Yes | This repo - see `.forgejo/workflows/build.yaml` |
+| **poimen** | ⏳ TBD | Yes (assumed) | Orchestrator - needs deployment |
+| **poimen-workflows** | ⏳ TBD | Maybe | Check if containerized |
+
+### Repos That Don't Need Docker
+
+| Repo | Status | Type | Notes |
+|------|--------|------|-------|
+| **homelab** | ✅ Done | K8s manifests | Validates with yamllint + kubeval |
+
+---
+
+## Implementation Checklist for Each Repo
+
+### Step 0: Prerequisites
+- [ ] Repo has a `Dockerfile`
+- [ ] Repo has a `.forgejo/` or `.gitea/` directory
+- [ ] Docker builds successfully: `docker build -t test:latest .`
+- [ ] Tests pass: `cargo test` / `npm test` / etc
+
+### Step 1: Create Workflow File
+```bash
+# Copy from poimen-memory:
+cp ~/workplace/Poimen/memory/.forgejo/workflows/build.yaml \
+   ~/workplace/Poimen/<repo>/.forgejo/workflows/build.yaml
+
+# Edit if needed:
+# - Change IMAGE_NAME from "rock/poimen-memory" to "rock/<your-repo>"
+# - Adjust test command if not Rust (cargo test)
+```
+
+### Step 2: Set Repository Secret
+```
+https://git.riotpiao.com/rock/<repo>/settings/secrets
+
+Add:
+- Name: REGISTRY_PAT
+- Value: <org-token-or-personal-token>
+```
+
+### Step 3: Commit & Push
+```bash
+git add .forgejo/workflows/build.yaml
+git commit -m "Add CI/CD: auto-build and push to registry"
+git push origin main
+```
+
+### Step 4: Create ArgoCD Application
+```bash
+# Create k8s/argocd/<repo>-app.yaml
+
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: poimen-<repo>-app
+  namespace: argocd
+spec:
+  project: homelab
+  source:
+    repoURL: https://forgejo.riotpiao.com/rock/poimen-<repo>.git
+    targetRevision: main
+    path: k8s/app  # adjust if different
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: poimen
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+```
+
+### Step 5: Apply Application
+```bash
+kubectl apply -f k8s/argocd/<repo>-app.yaml
+```
+
+### Done! ✅
+- Every push to main triggers:
+  1. Test suite
+  2. Docker build
+  3. Push to `forgejo.riotpiao.com/rock/<repo>:latest`
+  4. ArgoCD auto-deploys
+
+---
+
+## File Reference
+
+### Workflow Comparison
+
+**poimen-memory** (current):
+```yaml
+runs-on: golang
+container:
+  image: docker:27-cli
+  volumes:
+    - /docker-certs/client:/docker-certs/client:ro
+env:
+  DOCKER_HOST: tcp://localhost:2376
+  DOCKER_TLS_VERIFY: "1"
+  DOCKER_CERT_PATH: /docker-certs/client
+```
+
+**Why this setup:**
+- Runs on `golang` runner (has Docker daemon)
+- Uses Docker CLI in container with DinD (Docker-in-Docker)
+- TLS certs mounted for secure daemon access
+- Allows building AND pushing in same job
+
+### Test Job
+
+Adjust for your language:
+
+**Rust** (poimen-memory):
+```yaml
+runs-on: rust
+steps:
+  - uses: actions/checkout@v4
+  - run: cargo test --all
+```
+
+**Go**:
+```yaml
+runs-on: golang
+steps:
+  - uses: actions/checkout@v4
+  - run: go test ./...
+```
+
+**Node.js**:
+```yaml
+runs-on: docker
+steps:
+  - uses: actions/checkout@v4
+  - run: npm install && npm test
+```
+
+---
+
+## Organization-Wide Setup
+
+### One-Time: Set Organization Secret
+Instead of per-repo secrets, Forgejo supports organization secrets.
+
+**If available**, set `REGISTRY_PAT` at org level:
+```
+https://git.riotpiao.com/rock/settings/secrets
+```
+
+Then all repos automatically inherit it (no per-repo setup needed).
+
+**Check**: Try accessing org secrets settings
+- If available: set once, use everywhere
+- If not: set per-repo (5 minutes per repo)
+
+---
+
+## Monitoring & Troubleshooting
+
+### Build Failures
+
+**Check logs:**
+```
+https://git.riotpiao.com/rock/<repo>/actions
+```
+
+**Common issues:**
+- Test failures → Fix tests locally
+- Docker build error → Check Dockerfile syntax
+- Push fails → Verify REGISTRY_PAT token
+
+### Deployment Issues
+
+**Watch ArgoCD:**
+```bash
+kubectl get application -n argocd poimen-<repo>-app -w
+kubectl logs -n argocd argocd-application-controller | grep poimen
+```
+
+**Check pods:**
+```bash
+kubectl get pods -n poimen -l app.kubernetes.io/name=poimen-<repo> -w
+kubectl describe pod -n poimen <pod-name>
+```
+
+---
+
+## Summary
+
+**Effort**: ~10 minutes per repo (once)
+
+**Benefit**: 
+- Zero-touch deployments
+- Every commit automatically tested & deployed
+- Consistent across organization
+- No manual image pushes ever
+
+**Best practice**: Use org-level secret if available (1 setup, unlimited repos)
+
+---
+
+## Next Steps
+
+1. **poimen-memory**: ✅ Done (this repo)
+2. **poimen**: Set up workflow + secret
+3. **poimen-workflows**: Set up workflow + secret
+4. **Document in**: homelab-poimen-standard.md (org wiki)

CI-SETUP.md

@@ -1,40 +1,45 @@
-# CI/CD Setup — Forgejo Actions Registry Credentials
+# CI/CD Setup — Registry Push Configuration
 
-## Required Configuration
+## One-Time Setup
 
-The CI pipeline (`.forgejo/workflows/build.yaml`) automatically builds and pushes Docker images on each push to `main`. However, it requires registry credentials to be configured as repository secrets.
+The CI/CD pipeline automatically builds and pushes Docker images when you push to `main`.
 
-### Setup Steps
+### 1. Create or Get Registry Token
 
-#### 1. **Get Registry Credentials**
+**Option A: Use Organization Token** (Recommended)
-
-From the homelab setup:
 ```bash
-# Get ci-bot token (or use your personal access token)
+# Ask Rock for the existing 'rock' organization PAT
-kubectl get secret -n poimen $(kubectl get secret -n poimen -l app.kubernetes.io/name=ci-bot -o name | head -1) -o jsonpath='{.data.token}' | base64 -d
+# It should already have write:package permissions
 ```
 
-Or use a personal Forgejo access token:
+**Option B: Create Personal Token**
-- URL: https://forgejo.riotpiao.com/user/settings/tokens
+```bash
-- Create token with `write:package` scope
+# 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. **Set Repository Secrets**
+### 2. Add Repository Secret
 
 Go to: **https://git.riotpiao.com/rock/poimen-memory/settings/secrets**
 
-Add two secrets:
+Add secret:
-- **`REGISTRY_USER`**: `ci-bot` (or your username)
+- **Name**: `REGISTRY_PAT`
-- **`REGISTRY_TOKEN`**: `<token-from-step-1>`
+- **Value**: `<token-from-step-1>`
+- **Save**
 
-#### 3. **Verify Setup**
+### 3. Verify Setup
 
-Push a commit and check:
 ```bash
-# Via web UI
+# Push a commit (any change will do)
-https://git.riotpiao.com/rock/poimen-memory/actions
+cd ~/workplace/Poimen/memory
+git commit --allow-empty -m "Trigger CI build"
+git push origin main
 
-# Or check if image exists
+# Check Actions tab
-docker pull forgejo.riotpiao.com/rock/poimen-memory:latest
+# https://git.riotpiao.com/rock/poimen-memory/actions
 ```
 
 ---
@@ -42,82 +47,101 @@ docker pull forgejo.riotpiao.com/rock/poimen-memory:latest
 ## How It Works
 
 ```
-┌─────────────────┐
+Push to main
-│  Push to main   │
-└────────┬────────┘
-         │
     ↓
-┌─────────────────────────────────────────┐
+Forgejo Actions triggered
-│  Forgejo Actions (rust runner)          │
+    ↓
-│  1. cargo build --workspace             │
+Test:  cargo test --all
-│  2. cargo test --all                    │
-└────────┬────────────────────────────────┘
-         │
     ↓ (only if tests pass)
-┌─────────────────────────────────────────┐
+Build: docker build -t forgejo.riotpiao.com/rock/poimen-memory:latest .
-│  Build Docker Image                     │
-│  docker build -t forgejo.../latest .    │
-└────────┬────────────────────────────────┘
-         │
     ↓
-┌─────────────────────────────────────────┐
+Push:  docker push (using REGISTRY_PAT secret)
-│  Push to Registry                       │
-│  docker login + push                    │
-│  Uses: REGISTRY_USER + REGISTRY_TOKEN   │
-└────────┬────────────────────────────────┘
-         │
     ↓
-┌─────────────────────────────────────────┐
+ArgoCD detects new image
-│  ArgoCD Detects Image                   │
-│  Syncs k8s/app/ with new image          │
-└────────┬────────────────────────────────┘
-         │
     ↓
-┌─────────────────────────────────────────┐
+Auto-deploy to poimen namespace
-│  K8s Deployment                         │
+```
-│  Pulls new image, restarts pods         │
+
-└─────────────────────────────────────────┘
+---
+
+## 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
 
-### Build Fails During Tests
+### Secret Not Found Error
-- Check workflow logs: https://git.riotpiao.com/rock/poimen-memory/actions
+- Go to: https://git.riotpiao.com/rock/poimen-memory/settings/secrets
-- Run locally: `cargo test --all`
+- Verify `REGISTRY_PAT` is set
 
-### Image Not Pushing
+### Login Failed
-- Verify `REGISTRY_TOKEN` secret is set correctly
+- Token might be expired or revoked
-- Check docker login error in workflow logs
+- Create a new token and update the secret
-- Ensure token has `write:package` scope
 
-### ArgoCD Not Syncing
+### Build Failed
-```bash
+- Check Actions logs for the error
-kubectl get application -n argocd poimen-memory-app -o yaml | grep -A 5 status
+- 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`
 
 ---
 
-## Manual Alternative
+## Apply to Other Repos
 
-If CI is not working, you can push manually:
+The same setup works for all Poimen repos:
 
 ```bash
-# From homelab machine (has registry access)
+# For poimen, poimen-workflows, etc:
-cd ~/workplace/Poimen/memory
+# 1. Create .forgejo/workflows/build.yaml (copy from template below)
-cargo build --release
+# 2. Add REGISTRY_PAT secret
-docker build -t forgejo.riotpiao.com/rock/poimen-memory:latest .
+# 3. Push and watch it deploy
-docker push forgejo.riotpiao.com/rock/poimen-memory:latest
 ```
 
-But the goal is **zero-touch CI/CD**, so set up the secrets once and forget about it.
+**Template**: See `.forgejo/workflows/TEMPLATE.md` in this repo
 
 ---
 
-## Status
+## Pattern Overview
 
-- ✅ Workflow file: `.forgejo/workflows/build.yaml`
+**Based on**: homelab-frontend (proven production pattern)
-- ✅ ArgoCD App: `k8s/argocd/memory-app.yaml`
+- Uses `REGISTRY_PAT` secret ✓
-- ⏳ **Required**: Set `REGISTRY_USER` and `REGISTRY_TOKEN` secrets
+- Docker login + push ✓
-- ⏳ Then: Push to main, watch image build and deploy automatically
+- 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

QUICK-START.md

@@ -0,0 +1,80 @@
+# Quick Start — One-Time CI/CD Setup (3 minutes)
+
+## 🚀 Setup
+
+### 1. Get Registry Token
+```bash
+# Ask for the 'rock' org token (already has write:package)
+# OR create one: https://git.riotpiao.com/user/settings/tokens
+#   - Scope: write:package
+#   - Copy the token value
+```
+
+### 2. Add Secret to Repository
+```bash
+# Go to: https://git.riotpiao.com/rock/poimen-memory/settings/secrets
+# Add: Name=REGISTRY_PAT, Value=<token>
+# Save
+```
+
+### 3. Push to Trigger Build
+```bash
+cd ~/workplace/Poimen/memory
+git commit --allow-empty -m "Trigger CI"
+git push
+```
+
+---
+
+## ✨ That's It!
+
+After these 3 steps, every push automatically:
+- ✅ Runs all tests
+- ✅ Builds Docker image
+- ✅ Pushes to `forgejo.riotpiao.com/rock/poimen-memory:latest`
+- ✅ ArgoCD deploys to K8s
+
+---
+
+## 📊 Monitor
+
+```bash
+# Watch build
+https://git.riotpiao.com/rock/poimen-memory/actions
+
+# Watch deployment
+kubectl get pods -n poimen -l app.kubernetes.io/name=poimen-memory -w
+```
+
+---
+
+## 🧪 Test When Ready
+
+```bash
+# Port forward
+kubectl port-forward -n poimen svc/poimen-memory 8080:80 &
+
+# Health check
+curl http://localhost:8080/health
+```
+
+---
+
+## 🔄 Apply to Other Repos
+
+Same pattern for `poimen`, `poimen-workflows`, etc:
+
+1. Add `REGISTRY_PAT` secret
+2. Copy `.forgejo/workflows/build.yaml` from this repo
+3. Push
+
+See `CI-SETUP.md` for details.
+
+---
+
+## Pattern Details
+
+- **Based on**: homelab-frontend (proven pattern)
+- **Runner**: docker:27-cli (supports buildx)
+- **Tags**: commit SHA + "latest"
+- **No manual steps**: Fully automated