trent_larson
/
crowd-funder-for-time-pwa
4
1
Fork 2
Code Pull Requests 12 Releases 5 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1955 Commits
76 Branches
23 Tags
452 MiB
 
 
 
 
 
 
Tree: 1d27ba8403
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '1d27ba8403'
${ noResults }
crowd-funder-for-time-pwa/docker/README.md

12 KiB
Raw Blame History

TimeSafari Docker Setup

Overview

This directory contains Docker configuration files for building and deploying TimeSafari across different environments with full configurability.

Files

  • Dockerfile - Multi-stage Docker build for TimeSafari
  • nginx.conf - Main nginx configuration with security headers
  • default.conf - Production server configuration
  • staging.conf - Staging server configuration with relaxed caching
  • docker-compose.yml - Multi-environment Docker Compose setup
  • .dockerignore - Optimizes build context
  • run.sh - Convenient script to run different configurations

Quick Start

Using the Run Script (Recommended)

# Development mode with hot reloading
./docker/run.sh dev

# Staging mode for testing
./docker/run.sh staging

# Production mode
./docker/run.sh production

# Custom mode with environment variables
BUILD_MODE=staging ./docker/run.sh custom

# Show build arguments for a mode
./docker/run.sh dev --build-args

# Custom port and environment file
./docker/run.sh staging --port 9000 --env .env.test

Using Docker Compose

# Development environment with hot reloading
docker-compose up dev

# Staging environment
docker-compose up staging

# Production environment
docker-compose up production

# Custom environment with variables
BUILD_MODE=staging docker-compose up custom

Build Commands

Manual Docker Build

# Build production image (default)
docker build -t timesafari:latest .

# Build staging image
docker build --build-arg BUILD_MODE=staging -t timesafari:staging .

# Build development image
docker build --build-arg BUILD_MODE=development -t timesafari:dev .

# Build with custom arguments
docker build \
  --build-arg BUILD_MODE=staging \
  --build-arg NODE_ENV=staging \
  --build-arg VITE_PWA_ENABLED=true \
  -t timesafari:custom .

Run Container

# Run production container
docker run -d -p 80:80 timesafari:latest

# Run with environment file
docker run -d -p 80:80 --env-file .env.production timesafari:latest

# Run with custom environment variables
docker run -d -p 80:80 \
  -e VITE_APP_SERVER=https://myapp.com \
  -e VITE_DEFAULT_ENDORSER_API_SERVER=https://api.myapp.com \
  timesafari:latest

Configuration Options

Build Arguments

The Dockerfile supports these build arguments:

Argument Default Description
BUILD_MODE production Build mode: development, staging, or production
NODE_ENV production Node.js environment
VITE_PLATFORM web Vite platform type
VITE_PWA_ENABLED true Enable PWA features
VITE_DISABLE_PWA false Disable PWA features

Environment Variables

Docker Compose supports these environment variables:

Variable Default Description
BUILD_MODE production Build mode
NODE_ENV production Node environment
VITE_PLATFORM web Vite platform
VITE_PWA_ENABLED true Enable PWA
VITE_DISABLE_PWA false Disable PWA
DEV_PORT 5173 Development port
STAGING_PORT 8080 Staging port
PROD_PORT 80 Production port
DEV_ENV_FILE .env.development Development env file
STAGING_ENV_FILE .env.staging Staging env file
PROD_ENV_FILE .env.production Production env file

Environment Files

Create environment files for different deployments:

# .env.development
VITE_APP_SERVER=https://dev.timesafari.app
VITE_DEFAULT_ENDORSER_API_SERVER=https://dev-api.endorser.ch
VITE_DEFAULT_IMAGE_API_SERVER=https://dev-image-api.timesafari.app
VITE_DEFAULT_PARTNER_API_SERVER=https://dev-partner-api.endorser.ch
VITE_DEFAULT_PUSH_SERVER=https://dev.timesafari.app
VITE_PASSKEYS_ENABLED=true

# .env.staging
VITE_APP_SERVER=https://staging.timesafari.app
VITE_DEFAULT_ENDORSER_API_SERVER=https://staging-api.endorser.ch
VITE_DEFAULT_IMAGE_API_SERVER=https://staging-image-api.timesafari.app
VITE_DEFAULT_PARTNER_API_SERVER=https://staging-partner-api.endorser.ch
VITE_DEFAULT_PUSH_SERVER=https://staging.timesafari.app
VITE_PASSKEYS_ENABLED=true

# .env.production
VITE_APP_SERVER=https://timesafari.app
VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch
VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app
VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch
VITE_DEFAULT_PUSH_SERVER=https://timesafari.app
VITE_PASSKEYS_ENABLED=true

Build Modes

Development Mode

  • Target: development
  • Features: Hot reloading, development server
  • Port: 5173
  • Caching: Disabled
  • Use Case: Local development
./docker/run.sh dev
# or
docker build --target development -t timesafari:dev .

Staging Mode

  • Target: staging
  • Features: Production build with relaxed caching
  • Port: 8080 (mapped from 80)
  • Caching: Short-term (1 hour)
  • Use Case: Testing and QA
./docker/run.sh staging
# or
docker build --build-arg BUILD_MODE=staging -t timesafari:staging .

Production Mode

  • Target: production
  • Features: Optimized production build
  • Port: 80
  • Caching: Long-term (1 year for assets)
  • Use Case: Live deployment
./docker/run.sh production
# or
docker build -t timesafari:latest .

Custom Mode

  • Target: Configurable via BUILD_TARGET
  • Features: Fully configurable
  • Port: Configurable via CUSTOM_PORT
  • Use Case: Special deployments
BUILD_MODE=staging NODE_ENV=staging ./docker/run.sh custom

Advanced Usage

Custom Build Configuration

# Build with specific environment
docker build \
  --build-arg BUILD_MODE=staging \
  --build-arg NODE_ENV=staging \
  --build-arg VITE_PWA_ENABLED=false \
  -t timesafari:staging-no-pwa .

# Run with custom configuration
docker run -d -p 9000:80 \
  -e VITE_APP_SERVER=https://test.example.com \
  timesafari:staging-no-pwa

Docker Compose with Custom Variables

# Set environment variables
export BUILD_MODE=staging
export NODE_ENV=staging
export STAGING_PORT=9000
export STAGING_ENV_FILE=.env.test

# Run staging with custom config
docker-compose up staging

Multi-Environment Deployment

# Development
./docker/run.sh dev

# Staging in another terminal
./docker/run.sh staging --port 8081

# Production in another terminal
./docker/run.sh production --port 8082

Security Features

Built-in Security

  • Non-root user execution: All containers run as non-root users
  • Security headers: XSS protection, content type options, frame options
  • Rate limiting: API request rate limiting
  • File access restrictions: Hidden files and backup files blocked
  • Minimal attack surface: Alpine Linux base images

Security Headers

  • X-Frame-Options: SAMEORIGIN
  • X-Content-Type-Options: nosniff
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: strict-origin-when-cross-origin
  • Content-Security-Policy: Comprehensive CSP policy

Performance Optimizations

Caching Strategy

  • Static assets: 1 year cache with immutable flag (production)
  • HTML files: 1 hour cache (production) / no cache (staging)
  • Service worker: No cache
  • Manifest: 1 day cache (production) / 1 hour cache (staging)

Compression

  • Gzip compression: Enabled for text-based files
  • Compression level: 6 (balanced)
  • Minimum size: 1024 bytes

Nginx Optimizations

  • Sendfile: Enabled for efficient file serving
  • TCP optimizations: nopush and nodelay enabled
  • Keepalive: 65 second timeout
  • Worker processes: Auto-detected based on CPU cores

Health Checks

Built-in Health Checks

All services include health checks that:

  • Check every 30 seconds
  • Timeout after 10 seconds
  • Retry 3 times before marking unhealthy
  • Start checking after 40 seconds

Health Check Endpoints

  • Production/Staging: http://localhost/health
  • Development: http://localhost:5173

SSL/HTTPS Setup

SSL Certificates

For SSL deployment, create an ssl directory with certificates:

mkdir ssl
# Copy your certificates to ssl/ directory
cp your-cert.pem ssl/
cp your-key.pem ssl/

SSL Configuration

Use the production-ssl service in docker-compose:

docker-compose up production-ssl

Monitoring and Logging

Log Locations

  • Access logs: /var/log/nginx/access.log
  • Error logs: /var/log/nginx/error.log

Log Format

$remote_addr - $remote_user [$time_local] "$request" 
$status $body_bytes_sent "$http_referer" 
"$http_user_agent" "$http_x_forwarded_for"

Log Levels

  • Production: warn level
  • Staging: debug level
  • Development: Full logging

Troubleshooting

Common Issues

Build Failures

# Check build logs
docker build -t timesafari:latest . 2>&1 | tee build.log

# Verify dependencies
docker run --rm timesafari:latest npm list --depth=0

# Check build arguments
./docker/run.sh dev --build-args

Container Won't Start

# Check container logs
docker logs <container_id>

# Check health status
docker inspect <container_id> | grep -A 10 "Health"

# Verify port availability
netstat -tulpn | grep :80

Environment Variables Not Set

# Check environment in container
docker exec <container_id> env | grep VITE_

# Verify .env file
cat .env.production

# Check build arguments
./docker/run.sh production --build-args

Performance Issues

# Check container resources
docker stats <container_id>

# Check nginx configuration
docker exec <container_id> nginx -t

# Monitor access logs
docker exec <container_id> tail -f /var/log/nginx/access.log

Debug Commands

Container Debugging

# Enter running container
docker exec -it <container_id> /bin/sh

# Check nginx status
docker exec <container_id> nginx -t

# Check file permissions
docker exec <container_id> ls -la /usr/share/nginx/html

Network Debugging

# Check container network
docker network inspect bridge

# Test connectivity
docker exec <container_id> curl -I http://localhost

# Check DNS resolution
docker exec <container_id> nslookup google.com

Production Deployment

Recommended Production Setup

  1. Use specific version tags: timesafari:1.0.0
  2. Implement health checks: Already included
  3. Configure proper logging: Use external log aggregation
  4. Set up reverse proxy: Use nginx-lb service
  5. Use Docker secrets: For sensitive data

Production Commands

# Build with specific version
docker build -t timesafari:1.0.0 .

# Run with production settings
docker run -d \
  --name timesafari \
  -p 80:80 \
  --restart unless-stopped \
  --env-file .env.production \
  timesafari:1.0.0

# Update production deployment
docker stop timesafari
docker rm timesafari
docker build -t timesafari:1.0.1 .
docker run -d --name timesafari -p 80:80 --restart unless-stopped --env-file .env.production timesafari:1.0.1

Development Workflow

Local Development

# Start development environment
./docker/run.sh dev

# Make changes to code (hot reloading enabled)
# Access at http://localhost:5173

# Stop development environment
docker-compose down dev

Testing Changes

# Build and test staging
./docker/run.sh staging

# Test production build locally
./docker/run.sh production

Continuous Integration

# Build and test in CI
docker build -t timesafari:test .
docker run -d --name timesafari-test -p 8080:80 timesafari:test

# Run tests against container
curl -f http://localhost:8080/health

# Cleanup
docker stop timesafari-test
docker rm timesafari-test

Best Practices

Security

  • Always use non-root users
  • Keep base images updated
  • Scan images for vulnerabilities
  • Use secrets for sensitive data
  • Implement proper access controls

Performance

  • Use multi-stage builds
  • Optimize layer caching
  • Minimize image size
  • Use appropriate base images
  • Implement proper caching

Monitoring

  • Use health checks
  • Monitor resource usage
  • Set up log aggregation
  • Implement metrics collection
  • Use proper error handling

Maintenance

  • Regular security updates
  • Monitor for vulnerabilities
  • Keep dependencies updated
  • Document configuration changes
  • Test deployment procedures