This guide covers building and running nself-chat using Docker.

• Prerequisites
• Quick Start
• Building Images
• Local Development
• Production Deployment
• Configuration
• Troubleshooting

• Docker 20.10 or later
• Docker Compose v2 or later
• 4GB RAM minimum (8GB recommended)
• 10GB disk space

# Start all services
docker compose up -d

# View logs
docker compose logs -f nchat

# Stop services
docker compose down

The application will be available at:

• Application: http://localhost:3000
• Hasura Console: http://localhost:8080
• Mailpit: http://localhost:8025
• MinIO Console: http://localhost:9001

# Build with default tag (latest)
./scripts/docker-build.sh

# Build with specific tag
./scripts/docker-build.sh --tag v1.0.0

# Build and push to registry
./scripts/docker-build.sh --tag v1.0.0 --push

# Build for multiple platforms
./scripts/docker-build.sh --platform linux/amd64,linux/arm64

# Build development image
./scripts/docker-build.sh --dev

The Dockerfile accepts these build arguments:

Example:

docker build \
  --build-arg NEXT_PUBLIC_GRAPHQL_URL=https://api.example.com/v1/graphql \
  --build-arg NEXT_PUBLIC_AUTH_URL=https://auth.example.com \
  -t nself-chat:custom .

The development compose file includes:

• nchat: Next.js application with hot-reload
• postgres: PostgreSQL 16 database
• hasura: Hasura GraphQL Engine
• auth: Nhost authentication service
• storage: MinIO S3-compatible storage
• redis: Redis cache
• mailpit: Email testing server

Development uses volume mounts for hot-reload:

volumes:
  - .:/app
  - /app/node_modules # Exclude node_modules
  - /app/.next # Exclude build output

Copy the example environment file:

cp docker/.env.example docker/.env

Key variables:

# Development mode
NEXT_PUBLIC_USE_DEV_AUTH=true

# Auto-reload
WATCHPACK_POLLING=true

Production compose includes security hardening:

• Non-root user
• Read-only filesystem
• Resource limits
• Health checks
• Logging configuration

# Start production stack
docker compose -f docker-compose.prod.yml up -d

# With environment file
docker compose -f docker-compose.prod.yml --env-file docker/.env.production up -d

Required production variables:

# Database
POSTGRES_USER=nchat
POSTGRES_PASSWORD=<secure-password>
POSTGRES_DB=nchat

# Hasura
HASURA_ADMIN_SECRET=<secure-secret>
HASURA_JWT_SECRET='{"type":"HS256","key":"<32-char-secret>"}'

# Redis
REDIS_PASSWORD=<secure-password>

# SMTP
SMTP_HOST=smtp.example.com
SMTP_USER=<smtp-user>
SMTP_PASS=<smtp-password>

For production, configure SSL certificates:

1. Create SSL directory:

   mkdir -p docker/ssl

2. Add certificates:

   docker/ssl/cert.pem
   docker/ssl/key.pem

3. Nginx will automatically use these certificates.

Scale the application:

# Scale to 3 replicas
docker compose -f docker-compose.prod.yml up -d --scale nchat=3

The docker/nginx.conf provides:

• SSL termination
• Rate limiting
• Gzip compression
• Security headers
• WebSocket support
• Static asset caching

Customize rate limits:

# Adjust rate limits
limit_req_zone $binary_remote_addr zone=general:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=api:10m rate=30r/s;

All services include health checks:

healthcheck:
  test: ['CMD', 'curl', '-f', 'http://localhost:3000/api/health']
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

Configure logging driver:

logging:
  driver: 'json-file'
  options:
    max-size: '10m'
    max-file: '3'

For centralized logging, use:

logging:
  driver: 'fluentd'
  options:
    fluentd-address: 'localhost:24224'

# Check logs
docker compose logs nchat

# Check container status
docker compose ps

# Inspect container
docker inspect nchat-dev

# Verify postgres is running
docker compose ps postgres

# Check postgres logs
docker compose logs postgres

# Test connection
docker compose exec postgres psql -U postgres -d nchat

# Clean build cache
docker builder prune

# Rebuild without cache
./scripts/docker-build.sh --no-cache

Increase Docker memory limit (Docker Desktop):

• Settings > Resources > Memory > 8GB

Enable polling in development:

WATCHPACK_POLLING=true

Or in docker-compose.yml:

environment:
  - WATCHPACK_POLLING=true

If you encounter permission errors:

# Fix ownership
sudo chown -R $(id -u):$(id -g) .

# Or run as specific user
docker compose exec --user 1001 nchat sh

The production image is optimized:

Further optimization:

• Use output: 'standalone' in next.config.js
• Minimize dependencies
• Use multi-stage builds

1. Never commit secrets to docker-compose files
2. Use secrets management (Docker Secrets, Vault)
3. Scan images for vulnerabilities
4. Run as non-root user
5. Use read-only filesystems where possible
6. Limit resources to prevent DoS
7. Keep images updated with security patches

• Kubernetes Deployment
• Helm Deployment