This commit is contained in:
Test
+293
@@ -0,0 +1,293 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user