HypLab

Docker Production Deployment

Deploy HypLab to production using Docker and Docker Compose.

Docker Production Deployment

This guide covers deploying HypLab to production using Docker and Docker Compose.

Prerequisites

  • Docker 20.10+
  • Docker Compose 2.0+
  • Domain name (optional, for SSL)
  • MongoDB Atlas account (recommended) or self-hosted MongoDB
  • Redis Cloud account (recommended) or self-hosted Redis

Step 1: Clone Repository

git clone https://github.com/hyplabAI/hyplab.git
cd hyplab

Step 2: Configure Environment Variables

Backend Configuration

Create api/.env:

# Server
PORT=4096
NODE_ENV=production

# Database
MONGODB_URL=mongodb+srv://user:password@cluster.mongodb.net/hyplab?retryWrites=true&w=majority

# Redis
REDIS_URL=redis://user:password@redis-host:6379

# Security
JWT_SECRET=your-super-secret-jwt-key-change-this
SESSION_SECRET=your-super-secret-session-key-change-this

# Telemetry (optional)
TELEMETRY_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector.com/v1/traces
OTEL_SERVICE_NAME=api
OTEL_SERVICE_VERSION=1.0.0

# Logging
LOG_LEVEL=info

Frontend Configuration

Create app/.env.local:

# API URL
NEXT_PUBLIC_API_URL=https://api.yourdomain.com

# Telemetry (optional)
NEXT_PUBLIC_TELEMETRY_ENABLED=true
NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector.com
NEXT_PUBLIC_OTEL_SERVICE_NAME=app

Step 3: Production Docker Compose

Create docker/docker-compose.prod.yml:

version: '3.8'

services:
  gateway:
    build:
      context: ../api
      dockerfile: Dockerfile.prod
    ports:
      - '4096:4096'
    environment:
      - NODE_ENV=production
      - MONGODB_URL=${MONGODB_URL}
      - REDIS_URL=${REDIS_URL}
      - JWT_SECRET=${JWT_SECRET}
    env_file:
      - ../api/.env
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:4096/health']
      interval: 30s
      timeout: 10s
      retries: 3
    networks:
      - hyplab-network

  web:
    build:
      context: ../app
      dockerfile: Dockerfile.prod
    ports:
      - '4090:3000'
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
    env_file:
      - ../app/.env.local
    restart: unless-stopped
    depends_on:
      - gateway
    networks:
      - hyplab-network

networks:
  hyplab-network:
    driver: bridge

Step 4: Create Production Dockerfiles

Backend Dockerfile

Create api/Dockerfile.prod:

FROM node:22-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

FROM node:22-alpine

WORKDIR /app

COPY --from=builder /app/node_modules ./node_modules
COPY . .

EXPOSE 4096

CMD ["node", "src/index.js"]

Frontend Dockerfile

Create app/Dockerfile.prod:

FROM node:22-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run i18n:convert
RUN npm run build

FROM node:22-alpine

WORKDIR /app

ENV NODE_ENV=production

COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package*.json ./
COPY --from=builder /app/node_modules ./node_modules

EXPOSE 3000

CMD ["npm", "start"]

Step 5: Database Setup

  1. Create MongoDB Atlas account
  2. Create a cluster
  3. Create database user
  4. Whitelist your server IP
  5. Get connection string: mongodb+srv://user:password@cluster.mongodb.net/hyplab

Self-Hosted MongoDB

Add to docker-compose.prod.yml:

  mongodb:
    image: mongo:7
    volumes:
      - mongodb_data:/data/db
    ports:
      - "27017:27017"
    restart: unless-stopped
    networks:
      - hyplab-network

volumes:
  mongodb_data:

Step 6: Redis Setup

  1. Create Redis Cloud account
  2. Create database
  3. Get connection string: redis://user:password@host:port

Self-Hosted Redis

Add to docker-compose.prod.yml:

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"
    restart: unless-stopped
    networks:
      - hyplab-network

volumes:
  redis_data:

Step 7: SSL/TLS Configuration

Using Nginx Reverse Proxy

Create nginx/nginx.conf:

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com www.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    # Frontend
    location / {
        proxy_pass http://web:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    # API
    location /api {
        proxy_pass http://gateway:4096;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Obtain SSL Certificate

# Install Certbot
sudo apt-get update
sudo apt-get install certbot

# Obtain certificate
sudo certbot certonly --standalone -d yourdomain.com -d www.yourdomain.com

Step 8: Deploy

# Build and start services
docker compose -f docker/docker-compose.prod.yml up -d --build

# View logs
docker compose -f docker/docker-compose.prod.yml logs -f

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

Step 9: Health Checks

API Health Check

curl https://api.yourdomain.com/health

Expected response:

{
  "status": "healthy",
  "service": "api"
}

Frontend Health Check

curl https://yourdomain.com

Should return HTML (200 OK).

Step 10: Monitoring Setup

Enable Telemetry

Set in .env:

TELEMETRY_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector.com/v1/traces

Log Aggregation

Configure log aggregation (e.g., ELK, Loki, CloudWatch):

# Add to docker-compose.prod.yml
gateway:
  logging:
    driver: 'json-file'
    options:
      max-size: '10m'
      max-file: '3'

Scaling

Horizontal Scaling

gateway:
  deploy:
    replicas: 3
  # Use load balancer (nginx, traefik, etc.)

Resource Limits

gateway:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 2G
      reservations:
        cpus: '1'
        memory: 1G

Backup and Disaster Recovery

MongoDB Backup

# Manual backup
mongodump --uri="mongodb+srv://user:password@cluster.mongodb.net/hyplab" --out=/backup

# Automated backup (cron)
0 2 * * * mongodump --uri="..." --out=/backup/$(date +\%Y-\%m-\%d)

Redis Backup

# Redis persistence is enabled with AOF
# Backup Redis data directory
docker cp redis:/data /backup/redis-$(date +%Y-%m-%d)

Troubleshooting

Check Container Status

docker compose -f docker/docker-compose.prod.yml ps

View Logs

# All services
docker compose -f docker/docker-compose.prod.yml logs -f

# Specific service
docker compose -f docker/docker-compose.prod.yml logs -f gateway

Restart Services

docker compose -f docker/docker-compose.prod.yml restart

Next Steps

Telemetry

Configure OpenTelemetry tracing and structured logging for observability.

Kubernetes Deployment

Deploy HypLab to Kubernetes (EKS, GKE, AKS, or self-hosted).

On this page

Docker Production DeploymentPrerequisitesStep 1: Clone RepositoryStep 2: Configure Environment VariablesBackend ConfigurationFrontend ConfigurationStep 3: Production Docker ComposeStep 4: Create Production DockerfilesBackend DockerfileFrontend DockerfileStep 5: Database SetupMongoDB Atlas (Recommended)Self-Hosted MongoDBStep 6: Redis SetupRedis Cloud (Recommended)Self-Hosted RedisStep 7: SSL/TLS ConfigurationUsing Nginx Reverse ProxyObtain SSL CertificateStep 8: DeployStep 9: Health ChecksAPI Health CheckFrontend Health CheckStep 10: Monitoring SetupEnable TelemetryLog AggregationScalingHorizontal ScalingResource LimitsBackup and Disaster RecoveryMongoDB BackupRedis BackupTroubleshootingCheck Container StatusView LogsRestart ServicesNext Steps