poimen-workflows/DEPLOYMENT.md

Poimen Application Deployment

Overview

Poimen is a unified application consisting of three services:

• poimen-memory: Memory/Graph RAG service
• poimen-workflows: Temporal orchestration + API
• poimen-frontend: Next.js frontend

All services are deployed together as a single application in the poimen namespace.

Local Development

Prerequisites

• Docker
• Docker Compose
• Node.js 18+
• Go 1.21+
• Python 3.11+

Start Local Stack

docker-compose up -d

This starts:

• PostgreSQL (memory + workflows DBs)
• Redis (cache)
• Temporal (workflow orchestration)
• poimen-memory (8000)
• poimen-workflows (8080)
• poimen-workflows-worker
• poimen-frontend (3000)

Access Services

• Frontend: http://localhost:3000
• Workflows API: http://localhost:8080
• Memory API: http://localhost:8000
• Temporal UI: http://localhost:8233

Stop Stack

docker-compose down

Building & Pushing Images

Build All Services

./build-push.sh latest

Or specific services:

docker build -t forgejo.riotpiao.com/rock/poimen-memory:v1.0.0 ./memory
docker push forgejo.riotpiao.com/rock/poimen-memory:v1.0.0

Image Tagging Strategy

• latest: Development/staging
• v1.0.0, v1.0.1, etc.: Production releases
• main-{commit-hash}: CI/CD automated builds

Kubernetes Deployment

Prerequisites

• Kubernetes cluster (1.24+)
• kubectl configured
• Kustomize installed
• Registry credentials configured

Deploy to Cluster

cd k8s
./deploy.sh -a

Or with specific tags:

./deploy.sh -m v1.0.0 -w v1.0.0 -f v1.0.0

Verify Deployment

kubectl get pods -n poimen
kubectl get svc -n poimen
kubectl logs -n poimen -l app=poimen-workflows

Configuration

Environment Variables

Configure in k8s/poimen-application.yaml under spec.template.spec.env:

Common:

• TEMPORAL_HOST: Temporal server (default: temporal:7233)
• DATABASE_URL: PostgreSQL connection
• JWT_SECRET: JWT signing key
• LOG_LEVEL: debug|info|warn|error

Memory Service:

• REDIS_URL: Redis connection
• ELASTICSEARCH_URL: Optional full-text search

Workflows Service:

• MEMORY_SERVICE_URL: Internal memory service URL

Frontend:

• NEXT_PUBLIC_WORKFLOWS_API: External workflows API
• NEXT_PUBLIC_MEMORY_API: External memory API
• OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET: Auth provider

Secrets

Create secrets before deployment:

kubectl create secret generic poimen-db-credentials \
  --from-literal=memory-url="postgresql://..." \
  --from-literal=workflows-url="postgresql://..." \
  -n poimen

kubectl create secret generic poimen-secrets \
  --from-literal=jwt-secret="..." \
  --from-literal=oauth-client-id="..." \
  --from-literal=oauth-client-secret="..." \
  -n poimen

Architecture

┌─────────────────────────────────────────────┐
│             LoadBalancer Service            │
│          poimen-frontend:80→3000            │
└─────────────────┬───────────────────────────┘
                  │
          ┌───────┴────────┐
          ▼                ▼
   ┌──────────────┐  ┌──────────────┐
   │   Frontend   │  │  Workflows   │
   │   (3000)     │  │   API (8080) │
   │   2 replicas │  │  2 replicas  │
   └──────────────┘  └──────┬───────┘
          │                 │
          │           ┌─────┴─────┐
          │           ▼           ▼
          │      ┌─────────────────────┐
          │      │  Temporal Cluster   │
          │      │  (External)         │
          │      └─────────────────────┘
          │
          └──────────────────┬──────────────┐
                             ▼              ▼
                    ┌──────────────┐  ┌──────────────┐
                    │   Memory     │  │  PostgreSQL  │
                    │  (8000)      │  │  (5432)      │
                    │  1 replica   │  │              │
                    └──────────────┘  └──────────────┘

Scaling

Horizontal Scaling

Adjust replicas in k8s/poimen-application.yaml:

spec:
  replicas: 3  # Increase this

Or patch:

kubectl patch deployment poimen-workflows -p '{"spec":{"replicas":3}}' -n poimen

Resource Requests/Limits

Add to container spec:

resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

Monitoring & Logging

Check Status

kubectl get pods -n poimen -w
kubectl describe pod <pod-name> -n poimen
kubectl logs -n poimen -f -l app=poimen-workflows --all-containers=true

Health Checks

All services expose /health endpoint:

curl http://poimen-workflows:8080/health
curl http://poimen-memory:8000/health
curl http://poimen-frontend:3000/

Updates & Rollbacks

Rolling Update

./deploy.sh -w v1.0.1

Kubernetes automatically rolls out with health checks.

View Rollout Status

kubectl rollout status deploy/poimen-workflows -n poimen

Rollback

kubectl rollout undo deploy/poimen-workflows -n poimen

Troubleshooting

Services Can't Connect

Check service DNS:

kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup poimen-workflows

Database Migrations Failing

kubectl exec -it <workflows-pod> -n poimen -- \
  ./workflows migrate up

Temporal Worker Not Picking Up Activities

Check worker logs:

kubectl logs -n poimen -l app=poimen-workflows --all-containers=true | grep -i activity

Verify activities registered in cmd/worker/main.go

CI/CD Integration

GitHub Actions Example

name: Build & Push Poimen

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build & Push
        run: ./build-push.sh main-${{ github.sha }}

Automatic Deployment

Configure ArgoCD to watch k8s/ directory for updates.