Table of Contents

Self-Hosting with Docker

administrator technical

Guide to hosting OpenSimulator using Docker containers.

Introduction

Docker provides a lightweight, portable way to run OpenSimulator in containers. This approach offers better isolation, easier deployment, and simplified maintenance compared to traditional installation.

Benefits of Docker: * Easy deployment and scaling * Consistent environments * Simplified updates * Better resource isolation * Easy rollback

Prerequisites

System Requirements

Docker Requirements: * Docker Engine 20.10+ * Docker Compose 2.0+ * 4GB RAM minimum per container * 10GB storage per container

System: * Linux (recommended) * Windows with WSL2 * macOS with Docker Desktop

Installing Docker

Linux (Ubuntu/Debian): ```bash curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER ```

Windows: 1. Download Docker Desktop 2. Install with WSL2 backend 3. Restart system

macOS: 1. Download Docker Desktop 2. Install and start Docker 3. Verify installation

Docker Image Options

Official Images

OpenSimulator Docker: * Official OpenSimulator images available * Check Docker Hub for latest versions * Choose stable or development branches

Alternative Images: * Community-maintained images * Grid-specific images * Custom builds

Choosing an Image

For Caprica: * Use OpenSimulator-compatible image * Verify version compatibility * Check Caprica documentation

For Independent Grid: * Latest stable OpenSimulator * Include desired modules - Consider Robust services

Basic Docker Setup

Dockerfile Example

```dockerfile FROM opensimulator/opensimulator:latest

# Copy configuration COPY OpenSim.ini /opt/opensimulator/bin/ COPY Regions/ /opt/opensimulator/bin/Regions/

# Expose ports EXPOSE 9000 8002 8003

# Start OpenSimulator CMD [“mono”, “OpenSim.exe”] ```

Building the Image

```bash docker build -t my-opensim . ```

Docker Compose Setup

docker-compose.yml

```yaml version: '3.8'

services:

opensim:
  image: opensimulator/opensimulator:latest
  container_name: opensim-server
  ports:
    - "9000:9000"
    - "8002:8002"
    - "8003:8003"
  volumes:
    - ./bin/OpenSim.ini:/opt/opensimulator/bin/OpenSim.ini
    - ./bin/Regions:/opt/opensimulator/bin/Regions
    - ./data:/opt/opensimulator/bin/data
  environment:
    - MYSQL_HOST=mysql
    - MYSQL_DATABASE=opensim
    - MYSQL_USER=opensim
    - MYSQL_PASSWORD=yourpassword
  depends_on:
    - mysql
  restart: unless-stopped
mysql:
  image: mysql:8.0
  container_name: opensim-mysql
  environment:
    - MYSQL_ROOT_PASSWORD=rootpassword
    - MYSQL_DATABASE=opensim
    - MYSQL_USER=opensim
    - MYSQL_PASSWORD=yourpassword
  volumes:
    - mysql-data:/var/lib/mysql
  restart: unless-stopped

volumes:

mysql-data:

```

Running with Docker Compose

```bash # Start services docker-compose up -d

# View logs docker-compose logs -f

# Stop services docker-compose down

# Stop and remove volumes docker-compose down -v ```

Configuration

Volume Mounts

Configuration Files: ```yaml volumes:

  1. ./OpenSim.ini:/opt/opensimulator/bin/OpenSim.ini
  2. ./Regions:/opt/opensimulator/bin/Regions

```

Data Persistence: ```yaml volumes:

  1. ./data:/opt/opensimulator/bin/data
  2. mysql-data:/var/lib/mysql

```

Network Configuration

Bridge Network (Default): * Containers communicate via bridge network - Port mapping for external access - Simple setup

Host Network: * Better performance * Direct host networking - Less isolation

Custom Network: ```yaml networks:

opensim-net:
  driver: bridge

```

Connecting to Caprica

Grid Configuration

OpenSim.ini for Caprica: ```ini [Startup] gridmode = true

[GridInfo] gridname = “Your Region” loginuri = “https://g.caprica.xyz:9000” ```

Environment Variables: ```yaml environment:

  1. GRID_MODE=true

```

Maintenance

Updates

Updating the Image: ```bash docker-compose pull docker-compose up -d ```

Rebuilding from Source: ```bash docker-compose build –no-cache docker-compose up -d ```

Backups

Database Backup: ```bash docker exec opensim-mysql mysqldump -u opensim -p opensim > backup.sql ```

Volume Backup: ```bash docker run –rm -v opensim-data:/data -v $(pwd):/backup alpine tar czf /backup/backup.tar.gz /data ```

Automated Backup Script: ```bash #!/bin/bash DATE=$(date +%Y%m%d) docker exec opensim-mysql mysqldump -u opensim -pyourpassword opensim > /backups/mysql_$DATE.sql docker run –rm -v opensim-data:/data -v /backups:/backup alpine tar czf /backup/data_$DATE.tar.gz /data ```

Monitoring

Container Logs

```bash # View all logs docker-compose logs

# Follow logs docker-compose logs -f

# Specific service docker-compose logs opensim ```

Resource Monitoring

```bash # Container stats docker stats

# Specific container docker stats opensim-server ```

Health Checks

Add to docker-compose.yml: ```yaml healthcheck:

test: ["CMD", "curl", "-f", "http://localhost:9000"]
interval: 30s
timeout: 10s
retries: 3

```

Troubleshooting

Common Issues

Container Won't Start: * Check logs: `docker-compose logs` - Verify configuration files - Check port conflicts - Ensure volumes are mounted correctly

Database Connection Failed: * Verify MySQL container is running - Check connection string - Ensure network connectivity - Check credentials

Performance Issues: * Monitor resource usage - Increase container resources - Optimize database - Check Docker resource limits

Debug Mode

Enable Debug Logging: ```yaml environment:

  1. DEBUG=true

```

Interactive Shell: ```bash docker exec -it opensim-server /bin/bash ```

Security

Container Security

Run as Non-Root: ```yaml user: “1000:1000” ```

Read-Only Filesystem: ```yaml read_only: true tmpfs:

  1. /tmp

```

Resource Limits: ```yaml deploy:

resources:
  limits:
    cpus: '2'
    memory: 4G

```

Network Security

Private Networks: ```yaml networks:

opensim-net:
  internal: true

```

Exposed Ports: * Only expose necessary ports - Use firewall rules - Consider reverse proxy

Scaling

Multiple Regions

Multiple Containers: ```yaml services:

opensim-region1:
  image: opensimulator/opensimulator
  # ... configuration
opensim-region2:
  image: opensimulator/opensimulator
  # ... configuration

```

Load Balancing

Reverse Proxy: * Use Nginx or Traefik - Load balance across containers - SSL termination

Resources

Documentation

* Docker Documentation: https://docs.docker.com/ * Docker Compose: https://docs.docker.com/compose/ * OpenSimulator Docker: Check Docker Hub

Community

* Docker Community Forums - OpenSimulator Docker discussions - Caprica community

Next Steps

Now that you have Docker setup:

* Test your deployment - Configure backup automation - Set up monitoring - Plan for scaling

Docker simplifies OpenSimulator deployment and maintenance. Happy containerizing!