Docker Infrastructure Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The Docker infrastructure deployment within the Happy ecosystem primarily supports the happy-server, a Fastify-based backend API. This infrastructure is designed to provide a robust, containerized environment for the project's centralized API services, complementing the edge-native Cloudflare Workers implementation. It ensures a consistent runtime environment across development, staging, and production by encapsulating the Node.js runtime, system-level dependencies like FFmpeg and Python3, and the application code.
Sources: apps/server/docker/CLAUDE.md:14-18, CLAUDE.md:131-135
Core Infrastructure Architecture
The Docker deployment follows a multi-tier architecture involving the application server and several critical backing services. The application is built as a multi-stage Docker image to optimize size and security, separating the build environment from the minimal production runtime.
Component Overview
| Component | Technology | Description |
|---|---|---|
| App Server | Fastify (Node.js 20) | Opinionated TypeScript API server handling core logic and Socket.io connections. |
| Primary Database | PostgreSQL | Relational storage managed via Prisma ORM for persistent user and session data. |
| Pub/Sub & Cache | Redis | Facilitates event bus operations and cross-process synchronization. |
| Object Storage | S3-Compatible | Used for storing media, artifacts, and persistent file uploads. |
| Processing Tools | FFmpeg / Python3 | System-level utilities required within the container for media processing. |
Sources: apps/server/docker/CLAUDE.md:20-30, apps/server/docker/CLAUDE.md:175-180
System Data Flow
The following diagram illustrates how the Docker-based server interacts with external clients and backing services:
The server acts as a "zero-knowledge" relay; while it facilitates communication and stores data, end-to-end encryption ensures it cannot decrypt user content.
Sources: apps/server/docker/CLAUDE.md:195-200, CLAUDE.md:144-148
Deployment Environment Configuration
Infrastructure deployment is governed by strictly managed environment variables and secrets. Each environment (dev, staging, production) uses specific .env files to configure the containerized services.
Required Configuration Variables
| Variable | Requirement | Description |
|---|---|---|
DATABASE_URL | Required | PostgreSQL connection string for Prisma. |
REDIS_URL | Required | Connection string for the ioredis-based event bus. |
HAPPY_MASTER_SECRET | Required | 32-byte hex key for JWT signing and internal encryption. |
S3_ENDPOINT | Required | The endpoint for the S3-compatible storage service (e.g., MinIO). |
Sources: apps/server/docker/CLAUDE.md:52-65
Secret Management Flow
Secrets are generated using specialized scripts before being injected into the Docker runtime environment.
Sources: apps/server/docker/CLAUDE.md:68-70
Database & Persistence Layer
The Docker infrastructure relies on Prisma ORM to interact with the PostgreSQL database. A critical requirement for the deployment is that schema migrations are handled externally; the container is responsible for running yarn generate to update its local client types but should not perform migrations automatically in production.
Storage Service Interaction
The server utilizes an S3-compatible storage layer for artifacts. In the Dockerized environment, file uploads are handled non-transactionally to ensure performance and prevent long-running database locks.
Real-time and Sync Infrastructure
The Docker-based server utilizes Socket.io and Redis to maintain real-time synchronization between the Happy CLI and mobile clients.
WebSocket Relay Logic
- CLI Connection: The CLI establishes a WebSocket (WSS) connection to the Docker server.
- Event Distribution: When the CLI sends an encrypted update, the server uses the
eventbusmodule (Redis-backed) to distribute the update across all instances in the cluster. - Mobile Delivery: The server identifies active "user-scoped" or "session-scoped" connections and relays the encrypted payload.
Sources: apps/server/docker/CLAUDE.md:215-225, CLAUDE.md:140-145
Build and Runtime Specifications
The Dockerfile implements a two-stage build process to ensure the production image is lean and secure.
- Builder Stage: Installs all
devDependencies, including the Prisma CLI, and compiles TypeScript source code into JavaScript. It also generates the Prisma client based on the currentschema.prisma. - Runner Stage: Uses a Node.js 20 base image. It installs only production dependencies and ensures that system-level binaries (
ffmpeg,python3) are available in the$PATH. - Network: The container exposes port
3000by default.
Sources: apps/server/docker/CLAUDE.md:175-182
Runtime Troubleshooting
In Docker environments where the /tmp directory is mounted with noexec (common in secure Linux or Synology NAS deployments), the Prisma generator may fail. The infrastructure deployment requires setting the TMPDIR environment variable to a writable, executable directory within the project root (e.g., .tmp/) to allow binary execution.
Sources: apps/server/docker/CLAUDE.md:155-165
Summary
The Docker Infrastructure Deployment provides the backbone for the Happy ecosystem's centralized services. By utilizing a multi-stage build process and strictly defined environment configurations, it ensures a secure, scalable, and reproducible environment for the Fastify-based API server. This infrastructure effectively manages complex dependencies like PostgreSQL, Redis, and S3, while maintaining the project's core "zero-knowledge" security principle through encrypted data relay.