research-notes/ops.md

Operations: notes.orchard9.ai

Research notes journal deployed to orchard9 k3s fleet.

Architecture

┌─────────────┐   push    ┌─────────────┐  webhook   ┌─────────────┐
│   Local     │ ────────► │   Gitea     │ ─────────► │ Woodpecker  │
│   Dev       │           │ threesix.ai │            │     CI      │
└─────────────┘           └─────────────┘            └──────┬──────┘
                                                            │
                                                            ▼
┌─────────────┐  ingress  ┌─────────────┐  deploy   ┌─────────────┐
│   Browser   │ ◄──────── │    k3s      │ ◄──────── │   Kaniko    │
│ notes.      │           │  projects   │           │   build     │
│ orchard9.ai │           │  namespace  │           └──────┬──────┘
└─────────────┘           └─────────────┘                  │
                                                           ▼
                                                    ┌─────────────┐
                                                    │ Zot Registry│
                                                    │ registry.   │
                                                    │ threesix.ai │
                                                    └─────────────┘

Infrastructure

Component	Location
Domain	notes.orchard9.ai
DNS Provider	GoDaddy (via squiddy-dns)
Ingress IP	208.122.204.172
TLS	cert-manager / letsencrypt-prod
Registry	registry.threesix.ai
Git Origin	git.threesix.ai/jordan/research-notes
Namespace	projects

Local Development

cd blog
npm install      # or pnpm install
npm run dev      # http://localhost:19197

Deployment

Push to origin triggers automatic deployment:

git push origin main

Pipeline:

1. Woodpecker receives webhook from Gitea
2. Kaniko builds container image (amd64)
3. Image pushed to registry.threesix.ai/research-notes/web:${SHA}
4. kubectl rolls out new image to deployment

Initial Setup (one-time)

1. Create Gitea Repository

# Create repo at git.threesix.ai/jordan/research-notes
# Then set origin:
git remote add origin https://git.threesix.ai/jordan/research-notes.git

2. Configure DNS

squiddy-dns record create orchard9.ai A notes 208.122.204.172 \
  --ttl 300 --provider godaddy --profile orchard9

3. Apply Kubernetes Manifests

export KUBECONFIG=~/.kube/orchard9-k3sf.yaml
kubectl apply -f deploy/k8s/notes.yaml

4. First Deploy

git add .
git commit -m "Initial deployment setup"
git push origin main

Verify Deployment

# Check pod status
kubectl get pods -n projects -l app=research-notes

# Check ingress
kubectl get ingress -n projects research-notes

# Check TLS certificate
kubectl get certificate -n projects research-notes-tls

# View logs
kubectl logs -n projects -l app=research-notes --tail=50

# Port forward for debugging
kubectl port-forward -n projects svc/research-notes 8080:80

Troubleshooting

Build not triggering?

• Verify push went to origin (Gitea), not GitHub
• Check Woodpecker webhook exists on Gitea repo
• Check Woodpecker at ci.threesix.ai

Image not deploying?

# Check if image exists in registry
curl -s https://registry.threesix.ai/v2/research-notes/web/tags/list

# Check deployment events
kubectl describe deployment -n projects research-notes

TLS certificate not ready?

# Check certificate status
kubectl describe certificate -n projects research-notes-tls

# Check cert-manager logs
kubectl logs -n cert-manager -l app=cert-manager --tail=50

Files

File	Purpose
Dockerfile	Multi-stage Next.js standalone build
.woodpecker.yml	CI/CD pipeline config
deploy/k8s/notes.yaml	Deployment, Service, Ingress
blog/next.config.ts	Next.js config (standalone output)