ContextQMD
Back to Happy

Deployment

docs/deployment.md

33.1 KB
Original Source

Deployment

This document describes how to deploy the Happy backend (packages/happy-server) and the infrastructure it expects.

Runtime overview

  • App server: Node.js running tsx ./sources/main.ts (Fastify + Socket.IO).
  • Database: Postgres via Prisma.
  • Cache: Redis (currently used for connectivity and future expansion).
  • Object storage: S3-compatible storage for user-uploaded assets (MinIO works).
  • Metrics: Optional Prometheus /metrics server on a separate port.

Required services

  1. Postgres

    • Required for all persisted data.
    • Configure via DATABASE_URL.

  2. Redis

    • Required by startup (redis.ping() is called).
    • Configure via REDIS_URL.

  3. S3-compatible storage

    • Used for avatars and other uploaded assets.
    • Configure via S3_HOST, S3_PORT, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET, S3_PUBLIC_URL, S3_USE_SSL.

Environment variables

Required

  • DATABASE_URL: Postgres connection string.
  • HANDY_MASTER_SECRET: master key for auth tokens and server-side encryption.
  • REDIS_URL: Redis connection string.
  • S3_HOST, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET, S3_PUBLIC_URL: object storage config.

Common

  • PORT: API server port (default 3005).
  • METRICS_ENABLED: set to false to disable metrics server.
  • METRICS_PORT: metrics server port (default 9090).
  • S3_PORT: optional S3 port.
  • S3_USE_SSL: true/false (default true).

Optional integrations

  • GitHub OAuth/App: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_APP_ID, GITHUB_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET, plus redirect URL/URI.
    • GITHUB_REDIRECT_URL is used by the OAuth callback handler.
    • GITHUB_REDIRECT_URI is used by the GitHub App initializer.
  • Voice: ELEVENLABS_API_KEY (required for /v1/voice/token in production).
  • Debug logging: DANGEROUSLY_LOG_TO_SERVER_FOR_AI_AUTO_DEBUGGING (enables file logging + dev log endpoint).

Docker image

A production Dockerfile is provided at Dockerfile.server.

Key notes:

  • The server defaults to port 3005 (set PORT explicitly in container environments).
  • The image includes FFmpeg and Python for media processing.

Kubernetes manifests

Example manifests live in packages/happy-server/deploy:

  • handy.yaml: Deployment + Service + ExternalSecrets for the server.
  • happy-redis.yaml: Redis StatefulSet + Service + ConfigMap.

The deployment config expects:

  • Prometheus scraping annotations on port 9090.
  • A secret named handy-secrets populated by ExternalSecrets.
  • A service mapping port 3000 to container port 3005.

Local dev helpers

The server package includes scripts for local infrastructure:

  • yarn workspace happy-server db (Postgres in Docker)
  • yarn workspace happy-server redis
  • yarn workspace happy-server s3 + s3:init

Use .env/.env.dev to load local settings when running yarn workspace happy-server dev.

Implementation references

  • Entrypoint: packages/happy-server/sources/main.ts
  • Dockerfile: Dockerfile.server
  • Kubernetes manifests: packages/happy-server/deploy
  • Env usage: packages/happy-server/sources (rg -n "process.env")