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

```bash
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

```bash
docker-compose down
```

## Building & Pushing Images

### Build All Services

```bash
./build-push.sh latest
```

Or specific services:

```bash
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

```bash
cd k8s
./deploy.sh -a
```

Or with specific tags:

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

### Verify Deployment

```bash
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:

```bash
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`:

```yaml
spec:
  replicas: 3  # Increase this
```

Or patch:

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

### Resource Requests/Limits

Add to container spec:

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

## Monitoring & Logging

### Check Status

```bash
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:

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

## Updates & Rollbacks

### Rolling Update

```bash
./deploy.sh -w v1.0.1
```

Kubernetes automatically rolls out with health checks.

### View Rollout Status

```bash
kubectl rollout status deploy/poimen-workflows -n poimen
```

### Rollback

```bash
kubectl rollout undo deploy/poimen-workflows -n poimen
```

## Troubleshooting

### Services Can't Connect

Check service DNS:
```bash
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup poimen-workflows
```

### Database Migrations Failing

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

### Temporal Worker Not Picking Up Activities

Check worker logs:
```bash
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

```yaml
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.