SOP-005: Self-Hosting Server

DOCUMENT CONTROL

Field	Value
SOP ID	SOP-005
Version	1.0
Status	Active
Last Updated	December 2025

Purpose

This SOP provides instructions for self-hosting your own Happy relay server for complete control over your Claude Code mobile access.

Why Self-Host?

Benefit	Description
Total Privacy	Encrypted data stays on your hardware
No Limits	Set your own rate limits and storage
Team Control	Run one server for your whole team
Zero Dependencies	Never worry about service shutdown

Server Size

The entire server is only 1,293 lines of TypeScript. You can read it yourself to verify it just forwards encrypted messages.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    SELF-HOSTED SETUP                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐     ┌─────────────────┐     ┌─────────────┐   │
│  │ Your Phone  │────▶│ YOUR Server     │◀────│ Your Desktop│   │
│  │             │     │ (Self-Hosted)   │     │             │   │
│  └─────────────┘     └─────────────────┘     └─────────────┘   │
│                              │                                  │
│                      ┌───────┴───────┐                         │
│                      │   PostgreSQL  │                         │
│                      │   + Redis     │                         │
│                      └───────────────┘                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Procedure Flowchart

┌────────────────────┐
│       START        │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Clone server repo  │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Configure env vars │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Build Docker image │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Run with Docker    │
│ Compose            │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Configure devices  │
│ to use your server │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│     COMPLETE       │
└────────────────────┘

Step-by-Step Procedure

Step 1: Clone and Build

# Get the code
git clone https://github.com/slopus/happy-server
cd happy-server

# Build with Docker
docker build -t happy-server:latest .

Step 2: Configure Environment

Create a .env file:

NODE_ENV=production
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/happy-server
REDIS_URL=redis://localhost:6379
SEED=your-secure-random-seed-here
PORT=3005

Security

Replace SEED with a strong, random value for token generation.

Step 3: Docker Compose Setup

Create docker-compose.yml:

version: '3.8'
services:
  happy-server:
    image: happy-server:latest
    ports:
      - "3000:3000"
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/happy-server
      - REDIS_URL=redis://redis:6379
      - SEED=${SEED}
      - PORT=3005
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=happy-server
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Step 4: Run the Server

docker-compose up -d

Step 5: Set Up HTTPS (Production)

Using Caddy for automatic SSL:

# Install Caddy
sudo apt install caddy

# Configure reverse proxy
sudo tee /etc/caddy/Caddyfile <<EOF
your-domain.com {
    reverse_proxy localhost:3000
}
EOF

# Start Caddy
sudo systemctl restart caddy

Step 6: Configure Devices

On your phone:

1. Open Happy app
2. Go to Settings
3. Set "Relay Server URL" to https://your-domain.com
4. Save

On your computer:

export HAPPY_SERVER_URL="https://your-domain.com"
happy

Hosting Options

Option 1: Home Server (Free)

Device	Notes
Raspberry Pi	$35 one-time
Old laptop	Free
Mac Mini	Reuse existing
Desktop (always on)	Free

Option 2: Cloud VPS ($5-10/month)

Provider	Price
DigitalOcean	$6/month
Linode	$5/month
Vultr	$6/month
Hetzner	€4/month

Option 3: Corporate Network

Run inside your company network for team use.

System Requirements

For 1-10 developers:

• 512MB RAM
• 1 CPU core
• 10GB storage
• 100Mbps network

For 10-100 developers:

• 2GB RAM
• 2 CPU cores
• 100GB storage
• 1Gbps network

Monitoring

# View logs
docker logs -f happy-server

# Check health
curl http://localhost:3000/health

# See connection count
curl http://localhost:3000/stats

Backup

# Simple backup
tar -czf backup-$(date +%Y%m%d).tar.gz ./data

# Or sync to another location
rsync -av ./data/ backup-location/

Encrypted Backups

Backups are encrypted. No one can read them without your device keys.

Verification Checklist

• [ ] Docker containers running
• [ ] Health endpoint responds
• [ ] HTTPS certificate valid
• [ ] Phone connects to custom server
• [ ] Desktop CLI uses custom server
• [ ] Messages sync correctly

Related Documents

• SOP-002: Device Pairing
• Troubleshooting Guide