remoteturtle/DOCKER.md

🐳 Docker Deployment Guide

Quick Start

Production Deployment

Start everything with one command:

docker-compose up -d

This will:

• Build and start the backend server (ports 3001, 3002)
• Build and start the frontend client (port 3000)
• Set up networking between containers

Development Mode (with hot reload)

docker-compose -f docker-compose.dev.yml up

This enables:

• Hot reload for both server and client
• Volume mounting for live code changes
• Development dependencies

Architecture

┌─────────────────────────────────────┐
│         Zoraxy Reverse Proxy        │
│      (Your external proxy)          │
└────────┬────────────────┬───────────┘
         │                │
         │                │
    ┌────▼─────┐    ┌────▼─────┐
    │  Client  │    │  Server  │
    │  :3000   │    │  :3001   │
    │  (Vite)  │    │  :3002   │
    └──────────┘    └──────────┘
         │                │
         └────────┬───────┘
                  │
           turtle-network

Services

Backend Server (turtle-server)

• Ports: 3001 (HTTP), 3002 (WebSocket)
• Image: Built from server/Dockerfile
• Health Check: HTTP GET /api/turtles

Frontend Client (turtle-client)

• Port: 3000 (Vite preview server)
• Image: Built from client/Dockerfile
• Serves: Pre-built static React app

Docker Commands

Start Services

# Production (detached)
docker-compose up -d

# Development (with logs)
docker-compose -f docker-compose.dev.yml up

# Build and start
docker-compose up --build

Stop Services

docker-compose down

# Remove volumes too
docker-compose down -v

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f server
docker-compose logs -f client

Restart Services

# All services
docker-compose restart

# Specific service
docker-compose restart server

Shell Access

# Server container
docker-compose exec server sh

# Client container
docker-compose exec client sh

Zoraxy Configuration

Configure your Zoraxy reverse proxy to forward:

Frontend (Web UI)

• Domain: turtles.yourdomain.com (or your choice)
• Target: http://localhost:3000
• WebSocket: Enabled

Backend API

• Domain: turtles-api.yourdomain.com (or your choice)
• Target: http://localhost:3001
• WebSocket: Enabled (for port 3002)

Alternative: Single Domain Setup

Forward all /api/* requests to backend:

• Domain: turtles.yourdomain.com
• Path /: → http://localhost:3000 (Frontend)
• Path /api: → http://localhost:3001 (Backend)
• WebSocket: → ws://localhost:3002

Update Client Configuration

Edit client/src/store/turtleStore.js before building:

const WS_URL = 'wss://turtles.yourdomain.com/ws';  // or your WebSocket endpoint
const API_URL = 'https://turtles.yourdomain.com/api';  // or your API endpoint

Environment Variables

Create .env files if needed:

server/.env

NODE_ENV=production
PORT=3001
WS_PORT=3002

client/.env.production

VITE_API_URL=https://turtles-api.yourdomain.com
VITE_WS_URL=wss://turtles-api.yourdomain.com/ws

Building Images

Build all images

docker-compose build

Build specific service

docker-compose build server
docker-compose build client

Rebuild without cache

docker-compose build --no-cache

Minecraft Bridge Configuration

Update webbridge.lua to point to your Docker host:

-- If running on same machine
local SERVER_URL = "http://localhost:3001"

-- If running on different machine
local SERVER_URL = "http://YOUR_DOCKER_HOST_IP:3001"

-- If using Zoraxy reverse proxy
local SERVER_URL = "https://turtles-api.yourdomain.com"

Troubleshooting

Port Already in Use

# Check what's using the port
sudo lsof -i :3000
sudo lsof -i :3001

# Stop the containers
docker-compose down

# Remove any conflicting containers
docker ps -a
docker rm <container_id>

Container Won't Start

# Check logs
docker-compose logs server
docker-compose logs client

# Rebuild
docker-compose up --build

Can't Connect from Minecraft

• Verify firewall allows ports 3001-3002
• Check Docker host IP is correct
• Ensure HTTP API is enabled in ComputerCraft config
• Test: http.get("http://YOUR_IP:3001/api/turtles")

Health Check Failing

# Check container health
docker-compose ps

# Manually test health endpoint
curl http://localhost:3001/api/turtles
curl http://localhost:3000

Production Checklist

• Set up Zoraxy reverse proxy
• Configure SSL/TLS certificates
• Update API URLs in client code
• Build images: docker-compose build
• Start services: docker-compose up -d
• Verify health checks: docker-compose ps
• Test web interface
• Update Minecraft bridge script
• Test turtle connection

Updating the Application

# Pull latest code
git pull

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

# Or use rolling update
docker-compose up -d --build

Performance Tips

Reduce Image Size

• Images use Alpine Linux (minimal)
• Production builds exclude dev dependencies
• Multi-stage builds where applicable

Resource Limits

Add to docker-compose.yml:

services:
  server:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

Volume Management

# List volumes
docker volume ls

# Clean up unused volumes
docker volume prune

Backup and Restore

Backup Container Data

# Export container
docker export turtle-server > server-backup.tar
docker export turtle-client > client-backup.tar

Backup Logs

docker-compose logs > logs-backup.txt

Security

Best Practices

1. Use Zoraxy for SSL/TLS termination
2. Don't expose Docker ports directly to internet
3. Use environment variables for sensitive data
4. Keep Docker and images updated
5. Use non-root user in containers (already configured)

Network Isolation

Containers use turtle-network bridge network:

• Isolated from host network
• Can communicate with each other
• Exposed ports defined in docker-compose.yml

Monitoring

Container Stats

docker stats

Health Status

docker-compose ps

System Resources

docker system df

Common Issues

Problem: Client can't connect to server Solution: Make sure both containers are on same network and server is healthy

Problem: WebSocket connection fails through Zoraxy Solution: Enable WebSocket support in Zoraxy proxy rules

Problem: Changes not reflected after rebuild Solution: Use --no-cache flag: docker-compose build --no-cache

---

Summary

Start: docker-compose up -d Stop: docker-compose down Logs: docker-compose logs -f Rebuild: docker-compose up --build -d

Set up your Zoraxy reverse proxy to forward traffic to:

• Frontend: localhost:3000
• Backend: localhost:3001 + localhost:3002 (WebSocket)

Easy deployment with Docker + Zoraxy! 🐳✨