OrbitalSimulator/DOCKER.md

Docker Deployment Guide

This guide covers deploying the Orbital Simulator using Docker.

Quick Start

Development Deployment

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

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

Production Deployment with Nginx

# 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

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

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

Build with Custom Tag

# 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

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:

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

Persistent Logs

Mount logs directory for persistence:

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:

# 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:

# 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:

# 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:

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

Monitoring

Add monitoring with Prometheus/Grafana:

# 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

# 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:

# Check file permissions
ls -la config/

# Fix permissions if needed
chmod -R 644 config/

Memory Issues

For large simulations, increase container memory:

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

Building for Different Architectures

Multi-architecture Build

# 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):

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

Updates and Maintenance

Updating the Application

# 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:

# 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

# .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

# Scan for vulnerabilities
docker scan orbital-simulator