forked from trent_larson/crowd-funder-for-time-pwa
migration: move to bash based build scripts
This commit is contained in:
Matthew Raymer
509
docker/README.md
Normal file
509
docker/README.md
Normal file
@@ -0,0 +1,509 @@
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# .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
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
BUILD_MODE=staging NODE_ENV=staging ./docker/run.sh custom
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Build Configuration
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Build and test staging
|
||||
./docker/run.sh staging
|
||||
|
||||
# Test production build locally
|
||||
./docker/run.sh production
|
||||
```
|
||||
|
||||
### Continuous Integration
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user