OrbitalSimulator/DOCKER.md

# Docker Deployment Guide

This guide covers deploying the Orbital Simulator using Docker.

## Quick Start

### Development Deployment

```bash
# Build and run with Docker Compose
docker-compose up --build

# Access the application
open http://localhost:3000
```

### Production Deployment with Nginx

```bash
# Run with production profile (includes Nginx reverse proxy)
docker-compose --profile production up --build -d

# Access the application
open http://localhost
```

## Manual Docker Build

### Build the Image

```bash
# Build the Docker image
docker build -t orbital-simulator .

# Run the container
docker run -p 3000:3000 orbital-simulator
```

### Build with Custom Tag

```bash
# Build with version tag
docker build -t orbital-simulator:v1.0.0 .

# Push to registry (after login)
docker tag orbital-simulator:v1.0.0 your-registry/orbital-simulator:v1.0.0
docker push your-registry/orbital-simulator:v1.0.0
```

## Environment Variables

The application supports the following environment variables:

- `RUST_LOG`: Log level (default: `info`)
- `BIND_ADDRESS`: Server bind address (default: `0.0.0.0:3000`)

### Example with Environment Variables

```bash
docker run -p 3000:3000 \
  -e RUST_LOG=debug \
  -e BIND_ADDRESS=0.0.0.0:3000 \
  orbital-simulator
```

## Volume Mounts

### Configuration Files

Mount custom configuration files:

```bash
docker run -p 3000:3000 \
  -v $(pwd)/custom-config:/app/config:ro \
  orbital-simulator
```

### Persistent Logs

Mount logs directory for persistence:

```bash
docker run -p 3000:3000 \
  -v orbital-logs:/app/logs \
  orbital-simulator
```

## Health Checks

The container includes a health check that verifies the API is responding:

```bash
# Check container health
docker ps

# View health check logs
docker inspect --format='{{json .State.Health}}' <container-id>
```

## Production Considerations

### SSL/TLS Setup

For production, update the `nginx.conf` file and mount SSL certificates:

```yaml
# docker-compose.yml
services:
  nginx:
    volumes:
      - ./ssl:/etc/nginx/ssl:ro
      - ./nginx-prod.conf:/etc/nginx/nginx.conf:ro
```

### Resource Limits

Set appropriate resource limits:

```yaml
# docker-compose.yml
services:
  orbital-simulator:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          memory: 512M
```

### Scaling

For high availability, you can run multiple instances:

```yaml
# docker-compose.yml
services:
  orbital-simulator:
    scale: 3
    deploy:
      replicas: 3
```

### Monitoring

Add monitoring with Prometheus/Grafana:

```yaml
# docker-compose.yml
services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    ports:
      - "3001:3000"
```

## Troubleshooting

### Container Won't Start

```bash
# Check logs
docker logs <container-id>

# Run interactively for debugging
docker run -it --entrypoint /bin/bash orbital-simulator
```

### Permission Issues

The container runs as a non-root user. If you encounter permission issues:

```bash
# Check file permissions
ls -la config/

# Fix permissions if needed
chmod -R 644 config/
```

### Memory Issues

For large simulations, increase container memory:

```bash
# Run with more memory
docker run -p 3000:3000 --memory=4g orbital-simulator
```

## Building for Different Architectures

### Multi-architecture Build

```bash
# Create and use buildx builder
docker buildx create --use

# Build for multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 \
  -t orbital-simulator:latest --push .
```

### ARM64 Support

The Docker image supports ARM64 (Apple Silicon, ARM servers):

```bash
# Build specifically for ARM64
docker buildx build --platform linux/arm64 \
  -t orbital-simulator:arm64 .
```

## Updates and Maintenance

### Updating the Application

```bash
# Pull latest changes
git pull

# Rebuild and restart
docker-compose down
docker-compose up --build -d
```

### Database/State Cleanup

Since the application stores simulation state in memory, restart to clear:

```bash
# Restart containers
docker-compose restart

# Or rebuild for full cleanup
docker-compose down -v
docker-compose up --build -d
```

## CI/CD Integration

### GitHub Actions Example

```yaml
# .github/workflows/docker.yml
name: Docker Build and Push

on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
      
      - name: Login to Registry
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      
      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: |
            orbital-simulator:latest
            orbital-simulator:${{ github.sha }}
```

## Security Considerations

1. **Run as non-root**: The container runs as user `appuser`
2. **Read-only config**: Mount config directory as read-only
3. **Network security**: Use Nginx for SSL termination and rate limiting
4. **Update base images**: Regularly update the base Debian image
5. **Scan for vulnerabilities**: Use `docker scan` or similar tools

```bash
# Scan for vulnerabilities
docker scan orbital-simulator
```