# Docker Deployment Guide

This guide covers deploying your {{PROJECT_TITLE}} application using Docker.

## Prerequisites

- Docker Engine 20.10+ installed
- Docker Compose v2.0+ installed
- Basic understanding of containerization

## Quick Start

### 1. Build and Run with Docker Compose

```bash
# Build and start the container
pnpm docker:run

# Or build and run in foreground to see logs
pnpm docker:dev

# View logs
pnpm docker:logs

# Stop the container
pnpm docker:stop
```

### 2. Manual Docker Commands

```bash
# Build the Docker image
docker build -t {{PROJECT_NAME}}:latest .

# Run the container
docker run -d \
  --name {{PROJECT_NAME}} \
  -p 3000:3000 \
  --restart unless-stopped \
  {{PROJECT_NAME}}:latest

# Check container status
docker ps

# View logs
docker logs -f {{PROJECT_NAME}}
```

## Configuration

### Environment Variables

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

Key variables:

- `HOST_PORT`: Port to expose on host (default: 3000)
- `NODE_ENV`: Environment mode (development/production)
- `PORT`: Internal container port

### Using Different Ports

If port 3000 is already in use:

```bash
# Using environment variable
HOST_PORT=8080 docker compose up -d

# Or modify .env file
echo "HOST_PORT=8080" >> .env
docker compose up -d
```

## Production Deployment

### Security Best Practices

Our Docker setup includes:

- ✅ Multi-stage builds (smaller images)
- ✅ Non-root user execution
- ✅ Read-only filesystem
- ✅ Resource limits
- ✅ Health checks
- ✅ Security headers via Helmet.js

### Deployment Options

#### 1. Deploy to VPS/Cloud VM

```bash
# On your server
git clone <your-repo>
cd {{PROJECT_NAME}}
docker compose up -d
```

#### 2. Deploy to Container Services

**AWS ECS / Fargate:**

```bash
# Build and push to ECR
aws ecr get-login-password | docker login --username AWS --password-stdin <ecr-url>
docker build -t {{PROJECT_NAME}} .
docker tag {{PROJECT_NAME}}:latest <ecr-url>/{{PROJECT_NAME}}:latest
docker push <ecr-url>/{{PROJECT_NAME}}:latest
```

**Google Cloud Run:**

```bash
# Build and push to GCR
gcloud builds submit --tag gcr.io/$PROJECT_ID/{{PROJECT_NAME}}
gcloud run deploy --image gcr.io/$PROJECT_ID/{{PROJECT_NAME}} --platform managed
```

**Azure Container Instances:**

```bash
# Push to ACR
az acr build --registry <registry-name> --image {{PROJECT_NAME}} .
az container create --resource-group <rg> --name {{PROJECT_NAME}} --image <registry-name>.azurecr.io/{{PROJECT_NAME}}:latest
```

### Using a Reverse Proxy

For production, use Nginx or Traefik as a reverse proxy:

```nginx
# nginx.conf example
server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost: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;
        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;
    }
}
```

## Monitoring & Maintenance

### Health Checks

The application includes a health check endpoint:

```bash
curl http://localhost:3000/health
```

Docker Compose automatically monitors this endpoint.

### Viewing Logs

```bash
# All logs
pnpm docker:logs

# Last 100 lines
docker compose logs --tail 100

# Follow specific service
docker compose logs -f web
```

### Resource Usage

```bash
# Check resource usage
docker stats {{PROJECT_NAME}}

# Inspect container
docker inspect {{PROJECT_NAME}}
```

### Updating the Application

```bash
# Pull latest changes
git pull

# Rebuild and deploy
pnpm docker:stop
pnpm docker:run
```

## Troubleshooting

### Container Won't Start

1. Check logs: `docker compose logs web`
2. Verify port availability: `lsof -i :3000`
3. Check Docker daemon: `docker version`

### Build Failures

1. Clear Docker cache: `docker system prune -a`
2. Check Node version in Dockerfile matches local
3. Verify all files are included (check .dockerignore)

### Performance Issues

1. Increase resource limits in docker-compose.yml
2. Enable Docker BuildKit: `export DOCKER_BUILDKIT=1`
3. Use volume mounts for development only

### Connection Refused

1. Ensure container is running: `docker ps`
2. Check exposed ports: `docker port {{PROJECT_NAME}}`
3. Verify firewall rules allow traffic

## Advanced Configuration

### Custom Build Arguments

```bash
# Build with custom Node version
docker build --build-arg NODE_VERSION=20-alpine -t {{PROJECT_NAME}} .
```

### Multi-Environment Setup

```yaml
# docker-compose.prod.yml
version: '3.8'
services:
  web:
    environment:
      - NODE_ENV=production
      - API_URL=https://api.production.com
```

```bash
# Use production config
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

### Scaling

```bash
# Run multiple instances
docker compose up -d --scale web=3
```

## Security Considerations

1. **Secrets Management**: Never commit secrets. Use Docker secrets or environment variables
2. **Image Scanning**: Scan images for vulnerabilities: `docker scan {{PROJECT_NAME}}:latest`
3. **Update Base Images**: Regularly update Node.js Alpine base image
4. **Network Isolation**: Use custom networks for multi-container setups

## Useful Commands

```bash
# Clean up everything
pnpm docker:clean

# Restart container
docker compose restart

# Execute commands in container
docker compose exec web sh

# Copy files from container
docker cp {{PROJECT_NAME}}:/app/logs ./local-logs

# Backup data
docker compose exec web tar -czf - /app/data > backup.tar.gz
```

## Support

For issues specific to Docker deployment:

1. Check the [Docker documentation](https://docs.docker.com/)
2. Review container logs carefully
3. Ensure your Docker version meets requirements
4. File an issue with complete error logs