remoteturtle/DOCKER.md

# 🐳 Docker Deployment Guide

## Quick Start

### Production Deployment

Start everything with one command:
```bash
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)

```bash
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
```bash
# 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
```bash
docker-compose down

# Remove volumes too
docker-compose down -v
```

### View Logs
```bash
# All services
docker-compose logs -f

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

### Restart Services
```bash
# All services
docker-compose restart

# Specific service
docker-compose restart server
```

### Shell Access
```bash
# 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:
```javascript
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
```env
NODE_ENV=production
PORT=3001
WS_PORT=3002
```

### client/.env.production
```env
VITE_API_URL=https://turtles-api.yourdomain.com
VITE_WS_URL=wss://turtles-api.yourdomain.com/ws
```

## Building Images

### Build all images
```bash
docker-compose build
```

### Build specific service
```bash
docker-compose build server
docker-compose build client
```

### Rebuild without cache
```bash
docker-compose build --no-cache
```

## Minecraft Bridge Configuration

Update `webbridge.lua` to point to your Docker host:

```lua
-- 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
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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:
```yaml
services:
  server:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
```

### Volume Management
```bash
# List volumes
docker volume ls

# Clean up unused volumes
docker volume prune
```

## Backup and Restore

### Backup Container Data
```bash
# Export container
docker export turtle-server > server-backup.tar
docker export turtle-client > client-backup.tar
```

### Backup Logs
```bash
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
```bash
docker stats
```

### Health Status
```bash
docker-compose ps
```

### System Resources
```bash
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!** 🐳✨