Production Deployment Guide

Deploy the complete Zeq OS Hub on a VPS with Docker, nginx reverse proxy, and optional SSL.

Prerequisites

• VPS with 4GB+ RAM, 2+ CPU cores (Ubuntu 22.04 recommended)
• Docker 24+ and Docker Compose v2
• Domain (optional but recommended for SSL)
• Git

Quick Start

# Clone the repository
git clone https://github.com/hulyasmath/zeq-os.git zeq-os-hub
cd zeq-os-hub

# Configure environment
cp .env.example .env
nano .env  # Set your API keys and passwords

# Build and start everything
docker compose -f infra/docker/docker-compose.prod.yml up -d

# Build Docusaurus (static site)
cd docs && npm install && npm run build && cd ..

# Start nginx reverse proxy
docker build -t zeq-nginx infra/nginx/
docker run -d --name zeq-nginx \
  --network docker_default \
  -p 80:80 \
  -v $(pwd)/docs/build:/usr/share/nginx/docusaurus:ro \
  -v $(pwd)/apps/physics-wizard-game:/usr/share/nginx/apps/physics-wizard-game:ro \
  -v $(pwd)/apps/tesc:/usr/share/nginx/apps/tesc:ro \
  -v $(pwd)/apps/zeq-chat:/usr/share/nginx/apps/zeq-chat:ro \
  -v $(pwd)/apps/hite-encryption:/usr/share/nginx/apps/hite-encryption:ro \
  -v $(pwd)/apps/zeqboard:/usr/share/nginx/apps/zeqboard:ro \
  -v $(pwd)/apps/sync-chrome-extension:/usr/share/nginx/apps/sync-chrome-extension:ro \
  zeq-nginx

Your hub is now accessible at http://localhost (or your domain).

Environment Variables

Copy .env.example and configure these values:

# ── Domain ─────────────────────────────────
DOMAIN=http://localhost              # or https://your-domain.com

# ── AI (required for Zeq MI) ──────────────
OPENAI_API_KEY=sk-...                # OpenAI API key
ANTHROPIC_API_KEY=sk-ant-...         # Anthropic API key (optional)

# ── Security ───────────────────────────────
ZEQ_API_KEYS=your-api-key-here       # API Gateway authentication keys (comma-separated)
ZEQ_MI_JWT_SECRET=random-string      # Zeq MI session signing
RATE_LIMIT_RPM=100                   # API rate limit (requests per minute)
ALLOWED_ORIGINS=http://localhost      # CORS allowed origins

# ── Gitea ──────────────────────────────────
GITEA_ROOT_URL=http://localhost/git/  # Gitea URL behind nginx

# ── Discourse (optional) ──────────────────
DISCOURSE_DB_PASSWORD=change_me
SMTP_SERVER=smtp.example.com
SMTP_USER=
SMTP_PASSWORD=

# ── Databases ─────────────────────────────
MONGO_INITDB_ROOT_USERNAME=zeq
MONGO_INITDB_ROOT_PASSWORD=change_me

Service Routes

Once deployed, all services are accessible from a single domain:

Route	Service	First-Time Setup
/	Documentation (Docusaurus)	Ready immediately
/docs/sdk/getting-started	SDK Getting Started	Ready immediately
/api/	API Gateway	Test with curl /api/v1/status
/api-docs	Swagger API Docs	Ready immediately
/chat/	Zeq MI	Set API keys in .env, create account on first visit
/git/	Zeq Git	Create admin account on first visit
/search/	Zeq Search	Ready immediately
/services/wizard/docs	7-Step Wizard Swagger	Ready immediately
/services/forensic/	Forensic Suite	Ready immediately
/services/daemon/	Zeqond Daemon	Ready immediately
/apps/physics-wizard/	Physics Game	Ready immediately
/apps/tesc/	TESC Messaging	Ready immediately
/apps/hite/	HITE Encryption	Ready immediately
/apps/dashboard/	ZeqBoard	Ready immediately

Health Checks

Verify all services are running:

# nginx itself
curl http://localhost/nginx-health

# API Gateway
curl http://localhost/api-health

# Individual services
curl http://localhost/services/daemon/health
curl http://localhost/services/wizard/health
curl http://localhost/sync/health

SSL with Let's Encrypt

When you have a domain pointed at your VPS:

1. Edit infra/nginx/nginx.conf — uncomment the HTTPS server block at the bottom
2. Set your domain in server_name
3. Run certbot:

   docker exec -it zeq-nginx certbot --nginx -d your-domain.com --non-interactive --agree-tos -m your@email.com

4. Set up auto-renewal:

   # Add to crontab
   0 0 * * * docker exec zeq-nginx certbot renew --quiet

Updating

# Pull latest code
git pull origin main

# Rebuild and restart
docker compose -f infra/docker/docker-compose.prod.yml pull
docker compose -f infra/docker/docker-compose.prod.yml up -d

# Rebuild Docusaurus
cd docs && npm run build && cd ..

# Restart nginx to pick up new static files
docker restart zeq-nginx

Stopping

# Stop all services (keep data)
docker compose -f infra/docker/docker-compose.prod.yml down

# Stop and remove all data (fresh start)
docker compose -f infra/docker/docker-compose.prod.yml down -v

Resource Requirements

Component	RAM	CPU	Disk
API Gateway	256MB	0.5	50MB
Sync Engine	128MB	0.25	20MB
Zeq MI	512MB	1.0	500MB
Gitea	256MB	0.5	1GB+
MongoDB	512MB	0.5	1GB+
Zeq Search	256MB	0.25	100MB
Other services	512MB	1.0	200MB
Total	~3GB	~4 cores	~4GB