Deployment Guide

Comprehensive deployment documentation for production, development, and scaling Soothe.

Overview

This guide covers production deployment patterns, monitoring setup, security hardening, scaling strategies, and disaster recovery. For basic daemon management, see Daemon Management.

Quick Reference

Topic	Guide	Key Focus
Production Setup	Production Setup	Docker Compose, PostgreSQL, pgvector
Monitoring	Monitoring Guide	Langfuse, logs, health checks
Security	Security Hardening	Reverse proxy, TLS, access control
Scaling	Scaling Strategies	Horizontal scaling, load balancing
Backup & Recovery	Backup Recovery	PostgreSQL backup, disaster recovery

Deployment Architecture

Soothe supports three deployment tiers:

Tier 1: Local Development

┌─────────────┐
│ CLI/TUI     │
│ (WebSocket) │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Soothe     │
│  Daemon     │
│ (SQLite)    │
└─────────────┘

Best for: Development, testing, single-user environments

Configuration:

persistence:
  default_backend: sqlite

Tier 2: Single-Node Production

┌──────────────┐
│ CLI/TUI/Web  │
└──────┬───────┘
       │ WebSocket
       ▼
┌──────────────┐
│  Soothe      │
│  Daemon      │
└──────┬───────┘
       │ PostgreSQL
       ▼
┌──────────────┐
│ PostgreSQL   │
│ + pgvector   │
└──────────────┘

Best for: Small teams, moderate load (<100 concurrent threads)

Configuration: See Production Setup

Tier 3: Multi-Node Production

┌──────────────┐
│ Load Balancer│
└──────┬───────┘
       │
       ├─→ ┌──────────────┐
       │   │ Soothe Node 1│
       │   └──────┬───────┘
       │          │
       ├─→ ┌──────────────┐
       │   │ Soothe Node 2│
       │   └──────┬───────┘
       │          │
       └─────→ ┌──────────────┐
               │ PostgreSQL   │
               │ Cluster      │
               └──────────────┘

Best for: High availability, large teams (>100 concurrent threads)

Configuration: See Scaling Strategies

Deployment Checklist

Before deploying to production, verify:

Infrastructure

• PostgreSQL database configured and accessible
• pgvector extension installed
• Network connectivity between daemon and database
• Persistent storage mounted (Docker volumes)
• Reverse proxy configured (if exposing WebSocket/HTTP)

Security

• API keys stored securely (environment variables, secrets manager)
• TLS enabled on reverse proxy
• Authentication configured on reverse proxy
• Firewall rules set (database port, daemon ports)
• Security policy configured in config.yml

Monitoring

• Langfuse observability enabled (optional but recommended)
• Log collection configured
• Health checks enabled in Docker Compose
• Alerting configured for critical errors

Backup & Recovery

• PostgreSQL backup strategy implemented
• Disaster recovery plan documented
• Configuration files backed up
• Recovery testing performed

Quick Start: Production Deployment

Using Docker Compose (recommended):

# 1. Clone deployment files
cd soothe/deploy

# 2. Configure environment
cp env-example .env
vim .env  # Set API keys, passwords

# 3. Create config.yml
cp config.prod.yml config.yml

# 4. Deploy stack
docker compose up -d

# 5. Verify deployment
docker compose ps
docker compose logs soothed

See Production Setup for detailed steps.

Deployment Patterns

Pattern 1: Docker Compose (Recommended)

Pros:

• Single-command deployment
• Built-in health checks
• Automatic restarts
• Volume management
• Network isolation

Use: Standard production deployments

See: deploy/docker-compose.yml and Production Setup

Pattern 2: Kubernetes

Pros:

• Horizontal scaling
• Rolling updates
• Service mesh integration
• Advanced orchestration

Use: Large-scale, high-availability deployments

See: Scaling Strategies

Pattern 3: Bare Metal / systemd

Pros:

• Maximum control
• No container overhead
• Direct hardware access

Use: Specialized environments, performance-critical applications

See: Production Setup

Common Deployment Scenarios

Scenario 1: Development Team (10 users)

Setup:

• Single PostgreSQL instance (4 databases per RFC-802)
• Single Soothe daemon
• WebSocket transport (localhost)
• SQLite fallback for testing

Config (config.yml + daemon.yml):

# config.yml
persistence:
  default_backend: postgresql
  postgres_base_dsn: postgresql://user:pass@postgres-host:5432

# daemon.yml
transports:
  websocket:
    enabled: true
    host: 127.0.0.1
    port: 8765
thread_pool:
  request_timeout_seconds: 1209600  # 14d per turn; 0 = no cap

Scenario 2: Production Team (50 users)

Setup:

• PostgreSQL + pgvector (production-grade)
• Reverse proxy (nginx) with TLS
• WebSocket transport
• Langfuse observability

Config (config.yml + daemon.yml):

# config.yml
persistence:
  default_backend: postgresql
  
observability:
  langfuse:
    enabled: true
    public_key: ${LANGFUSE_PUBLIC_KEY}
    secret_key: ${LANGFUSE_SECRET_KEY}

# daemon.yml
transports:
  websocket:
    enabled: true
    host: 127.0.0.1
    port: 8765
thread_pool:
  request_timeout_seconds: 1209600

Scenario 3: Large Organization (500 users)

Setup:

• PostgreSQL cluster (primary + replicas)
• Multiple Soothe nodes (horizontal scaling)
• Load balancer (nginx/HAProxy)
• Redis for distributed coordination
• Kafka for event streaming

Config: See Scaling Strategies

Post-Deployment Tasks

After successful deployment:

1. Verify Connectivity

# Test daemon health
soothed status

# Test database connection
psql -h postgres-host -U user -d soothe_checkpoints -c "SELECT 1"

# Test API connectivity (if WebSocket/HTTP enabled)
curl http://localhost:8765/health

2. Configure Observability

observability:
  langfuse:
    enabled: true
    host: https://your-langfuse-instance.com
  log_file_path: /var/log/soothe/soothed.log
  log_file_level: INFO

3. Set Up Monitoring

• Enable health checks in Docker Compose
• Configure log aggregation (ELK, Loki, etc.)
• Set up alerting (PagerDuty, Slack, etc.)

See Monitoring Guide

4. Implement Backup Strategy

# PostgreSQL backup
pg_dump -h postgres-host -U user soothe_checkpoints > backup.sql

# Docker volume backup
docker run --rm -v soothe_postgres_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/postgres_data.tar.gz /data

See Backup Recovery

5. Security Hardening

security:
  allow_paths_outside_workspace: false
  denied_paths:
    - /etc/**
    - ~/.ssh/**
    - ~/.aws/**

See Security Hardening

Troubleshooting

Deployment Issues

Issue	Solution	Reference
PostgreSQL connection fails	Check DSN, credentials, firewall	Production Setup
Daemon won’t start	Check config.yml syntax, logs	Troubleshooting
WebSocket connection refused	Enable transport, check port	Daemon Management
pgvector extension missing	Install extension, restart PostgreSQL	Production Setup

Performance Issues

Issue	Solution	Reference
Slow thread resumption	Tune PostgreSQL pool size	Scaling Strategies
Memory exhaustion	Limit parallel goals, adjust pool	Scaling Strategies
High latency	Enable connection pooling, optimize queries	Scaling Strategies

Next Steps

1. Production Setup: Follow Production Setup Guide for detailed deployment steps
2. Monitoring: Configure observability with Monitoring Guide
3. Security: Harden deployment with Security Hardening
4. Scaling: Plan growth with Scaling Strategies
5. Backup: Protect data with Backup Recovery

Related Documentation

• Configuration Guide - Complete YAML reference
• Daemon Management - Daemon lifecycle
• Transport Setup - WebSocket configuration
• Authentication - Reverse proxy authentication
• Troubleshooting - Common issues and solutions

---

Need help? See Troubleshooting or check the Soothe repository.

---

Table of contents

• Production Setup
• Monitoring and Observability
• Security Hardening
• Scaling Strategies
• Backup and Recovery