OrbitalSimulator/DEPLOYMENT.md

Production Deployment Guide

This guide explains how to build and deploy the Orbital Simulator in production environments.

Building for Production

1. Rust API Server

Build the optimized API server:

# Build without GUI dependencies (recommended for servers)
cargo build --release --bin api_server --no-default-features

# Or build with GUI support (if system libraries are available)
cargo build --release --bin api_server --features gui

The compiled binary will be at target/release/api_server.

2. Web Frontend

Build the optimized web frontend:

cd web
npm install
npm run build

The built files will be in web/dist/.

3. Desktop GUI (Optional)

Build the desktop application:

# Install Tauri CLI if not already installed
cargo install tauri-cli

# Build the desktop app
cargo tauri build --features gui

The built application will be in src-tauri/target/release/bundle/.

Deployment Options

Option 1: Single Server Deployment

Deploy both API and web frontend on the same server:

# 1. Copy the API server binary
cp target/release/api_server /opt/orbital_simulator/

# 2. Copy the web files
cp -r web/dist /opt/orbital_simulator/static

# 3. Create systemd service
sudo tee /etc/systemd/system/orbital-simulator.service > /dev/null <<EOF
[Unit]
Description=Orbital Simulator API Server
After=network.target

[Service]
Type=simple
User=orbital
WorkingDirectory=/opt/orbital_simulator
ExecStart=/opt/orbital_simulator/api_server
Restart=always
RestartSec=10
Environment=STATIC_DIR=/opt/orbital_simulator/static

[Install]
WantedBy=multi-user.target
EOF

# 4. Start the service
sudo systemctl enable orbital-simulator
sudo systemctl start orbital-simulator

Option 2: Separate API and Web Servers

API Server (Backend)

# Deploy API server only
cp target/release/api_server /opt/orbital_simulator/

Configure reverse proxy (nginx example):

server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:4395;
        proxy_set_header Host $host;
        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;
    }
}

Web Frontend (Static Hosting)

Deploy web/dist/ to any static hosting service:

• Nginx: Copy files to web root
• Apache: Copy files to document root
• CDN: Upload to AWS S3, Cloudflare, etc.

Update the API endpoint in the frontend if needed.

Option 3: Docker Deployment

Create Dockerfile:

# Multi-stage build
FROM rust:1.70 as rust-builder
WORKDIR /app
COPY Cargo.toml Cargo.lock ./
COPY src ./src
COPY build.rs ./
RUN cargo build --release --bin api_server --no-default-features

FROM node:18 as web-builder
WORKDIR /app
COPY web/package*.json ./
RUN npm install
COPY web ./
RUN npm run build

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY --from=rust-builder /app/target/release/api_server ./
COPY --from=web-builder /app/dist ./static
EXPOSE 4395
CMD ["./api_server"]

Build and run:

docker build -t orbital-simulator .
docker run -p 4395:4395 orbital-simulator

Configuration

Environment Variables

• PORT: Server port (default: 4395)
• HOST: Server host (default: 0.0.0.0)
• STATIC_DIR: Directory for static files (default: web/dist)
• LOG_LEVEL: Logging level (debug, info, warn, error)
• MAX_SIMULATIONS: Maximum concurrent simulations (default: 10)

Example Production Configuration

export PORT=8080
export HOST=0.0.0.0
export LOG_LEVEL=info
export MAX_SIMULATIONS=50
export STATIC_DIR=/var/www/orbital-simulator

Performance Tuning

Rust API Server

1. Enable release optimizations in Cargo.toml:

   [profile.release]
   opt-level = 3
   lto = true
   codegen-units = 1
   panic = 'abort'
   

2. Limit concurrent simulations to prevent resource exhaustion

3. Use connection pooling for database connections (if added)

Web Frontend

1. Enable gzip compression in your web server
2. Set appropriate cache headers for static assets
3. Use a CDN for global distribution
4. Implement lazy loading for large datasets

Monitoring and Logging

Metrics to Monitor

• API response times
• Active simulation count
• Memory usage
• CPU usage
• WebSocket connection count

Logging

The application uses the log crate. Configure logging level:

RUST_LOG=info ./api_server

Log levels:

• debug: Detailed debugging information
• info: General operational information
• warn: Warning messages
• error: Error messages only

Health Checks

The API server provides health check endpoints:

• GET /api/health: Basic health check
• GET /api/metrics: System metrics (if enabled)

Security Considerations

1. Use HTTPS in production
2. Configure CORS appropriately for your domain
3. Implement rate limiting to prevent abuse
4. Sanitize user inputs in configuration uploads
5. Run with minimal privileges (non-root user)
6. Keep dependencies updated regularly

Backup and Recovery

Data to Backup

• Configuration files
• Simulation results (if persisted)
• User data (if user accounts are added)

Recovery Procedures

1. Restore application binary
2. Restore configuration files
3. Restart services
4. Verify functionality

Scaling

Horizontal Scaling

• Deploy multiple API server instances behind a load balancer
• Use Redis for session storage (if sessions are added)
• Implement proper service discovery

Vertical Scaling

• Increase server resources (CPU, RAM)
• Optimize simulation algorithms
• Use faster storage (SSD)

Troubleshooting

Common Issues

1. Port already in use: Change PORT environment variable
2. Static files not found: Check STATIC_DIR path
3. High memory usage: Limit concurrent simulations
4. Slow performance: Enable release optimizations

Debug Mode

Run with debug logging:

RUST_LOG=debug ./api_server

Performance Profiling

Use perf or valgrind to profile the application:

perf record --call-graph=dwarf ./api_server
perf report

Support

For issues and questions:

1. Check the logs for error messages
2. Verify configuration settings
3. Test with minimal configuration
4. Consult the main README.md for additional information