GeoGuessrMCP/DEPLOYMENT.md

Production Deployment Guide - VPS with SSL

This guide covers deploying the GeoGuessr MCP Server to your VPS using your existing nginx-proxy-manager for SSL/HTTPS.

Prerequisites

• VPS with Docker and Docker Compose installed
• Existing nginx-proxy-manager running (port 81 for admin interface)
• Domain or subdomain pointing to your VPS (e.g., geoguessr-mcp.yourdomain.com)
• Docker Hub account (for hosting your image)

Deployment Architecture

                                    ┌─────────────────────┐
Internet ──────HTTPS (443)─────────►│ nginx-proxy-manager │
                                    │   (Firefly stack)   │
                                    └──────────┬──────────┘
                                               │
                                 firefly_network (Docker network)
                                               │
                          ┌────────────────────┼────────────────────┐
                          │                    │                    │
                    ┌─────▼──────┐      ┌──────▼──────┐    ┌───────▼────────┐
                    │  Firefly   │      │  GeoGuessr  │    │  Other apps... │
                    │    App     │      │  MCP Server │    │                │
                    └────────────┘      └─────────────┘    └────────────────┘

Step 1: Build and Push Docker Image

1.1 Build the Image

On your local machine or directly on the VPS:

# Navigate to project directory
cd /path/to/GeoGuessrMCP

# Build the image
docker build -t yourusername/geoguessr-mcp:latest .

# Optional: Build multi-architecture image (if deploying to ARM64)
docker buildx build --platform linux/amd64,linux/arm64 \
  -t yourusername/geoguessr-mcp:latest --push .

1.2 Push to Docker Hub

# Login to Docker Hub
docker login

# Push the image
docker push yourusername/geoguessr-mcp:latest

# Optionally tag with version
docker tag yourusername/geoguessr-mcp:latest yourusername/geoguessr-mcp:v1.0.0
docker push yourusername/geoguessr-mcp:v1.0.0

Step 2: Prepare VPS Directory

2.1 Create Project Directory

# SSH into your VPS
ssh user@your-vps-ip

# Create directory at same level as /firefly
cd /
sudo mkdir -p geoguessr-mcp
sudo chown $USER:$USER geoguessr-mcp
cd geoguessr-mcp

2.2 Upload Required Files

Transfer these files to your VPS /geoguessr-mcp directory:

• docker-compose.prod.yml
• .env (production configuration)

# From your local machine
scp docker-compose.prod.yml user@your-vps-ip:/geoguessr-mcp/
scp .env.production user@your-vps-ip:/geoguessr-mcp/.env

2.3 Configure Environment Variables

# On VPS - edit .env file
cd /geoguessr-mcp
nano .env

Update the following variables:

# Docker image configuration
DOCKER_USERNAME=yourusername
IMAGE_TAG=latest

# GeoGuessr authentication (REQUIRED for most features)
GEOGUESSR_NCFA_COOKIE=your_ncfa_cookie_here

# Monitoring (recommended for production)
MONITORING_ENABLED=true
MONITORING_INTERVAL_HOURS=24

# Logging
LOG_LEVEL=INFO

# Schema cache directory (default is fine)
SCHEMA_CACHE_DIR=/app/data/schemas

Step 3: Deploy the Container

3.1 Pull and Start the Container

cd /geoguessr-mcp

# Pull the latest image
docker compose -f docker-compose.prod.yml pull

# Start the service
docker compose -f docker-compose.prod.yml up -d

# Check logs
docker compose -f docker-compose.prod.yml logs -f

3.2 Verify Container is Running

# Check container status
docker ps | grep geoguessr-mcp

# Check health status
docker inspect geoguessr-mcp-server --format='{{.State.Health.Status}}'

# Should output: healthy

Step 4: Configure nginx-proxy-manager

4.1 Access nginx-proxy-manager Admin

1. Open browser and navigate to: http://your-vps-ip:81
2. Login with your credentials (default: admin@example.com / changeme)

4.2 Add Proxy Host

1. Click "Hosts" → "Proxy Hosts" → "Add Proxy Host"

2. Details Tab:

   • Domain Names: geoguessr-mcp.yourdomain.com (your subdomain)
   • Scheme: http
   • Forward Hostname/IP: geoguessr-mcp-server (container name)
   • Forward Port: 8000
   • Cache Assets: ✓ (enable)
   • Block Common Exploits: ✓ (enable)
   • Websockets Support: ✓ (enable - required for MCP)

3. SSL Tab:

   • SSL Certificate: Select "Request a new SSL Certificate"
   • Force SSL: ✓ (enable)
   • HTTP/2 Support: ✓ (enable)
   • HSTS Enabled: ✓ (enable)
   • Email Address for Let's Encrypt: your-email@example.com
   • I Agree to the Let's Encrypt Terms of Service: ✓

4. Click "Save"

nginx-proxy-manager will now:

• Request an SSL certificate from Let's Encrypt
• Configure automatic HTTPS redirection
• Proxy requests to your GeoGuessr MCP container

4.3 Verify SSL is Working

# Test the endpoint
curl https://geoguessr-mcp.yourdomain.com/health

# Should return: {"status": "healthy"}

Step 5: Connect Claude Desktop

5.1 Update Claude Desktop Configuration

On your local machine, edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "geoguessr-mcp": {
      "url": "https://geoguessr-mcp.yourdomain.com"
    }
  }
}

5.2 Restart Claude Desktop

Close and reopen Claude Desktop. The MCP server should now appear in the tools list.

Step 6: Monitoring and Maintenance

6.1 View Logs

# Follow logs in real-time
docker compose -f docker-compose.prod.yml logs -f geoguessr-mcp

# View last 100 lines
docker compose -f docker-compose.prod.yml logs --tail=100 geoguessr-mcp

6.2 Update the Application

cd /geoguessr-mcp

# Pull latest image
docker compose -f docker-compose.prod.yml pull

# Recreate container with new image
docker compose -f docker-compose.prod.yml up -d

# Remove old images
docker image prune -f

6.3 Backup Schema Data

The schema cache is persisted in a Docker volume. To backup:

# Create backup directory
mkdir -p ~/backups

# Backup the volume
docker run --rm \
  -v geoguessr-mcp-schemas-prod:/data \
  -v ~/backups:/backup \
  alpine tar czf /backup/geoguessr-schemas-$(date +%Y%m%d).tar.gz -C /data .

6.4 SSL Certificate Renewal

Let's Encrypt certificates are valid for 90 days. nginx-proxy-manager automatically renews them. To manually check:

1. Go to nginx-proxy-manager admin (port 81)
2. Navigate to "SSL Certificates"
3. Check expiry date
4. Click "Renew" if needed

Troubleshooting

Container Won't Start

# Check logs for errors
docker compose -f docker-compose.prod.yml logs geoguessr-mcp

# Common issues:
# - Missing .env file
# - Invalid NCFA cookie
# - Network connection issues

SSL Certificate Failed

1. Ensure DNS is pointing to your VPS IP
2. Check firewall allows ports 80 and 443
3. Verify email address is valid
4. Check nginx-proxy-manager logs:

docker logs proxy_app

Can't Connect from Claude Desktop

1. Verify container is healthy: docker ps
2. Test locally on VPS: curl http://localhost:8000/health
3. Test through proxy: curl https://geoguessr-mcp.yourdomain.com/health
4. Check nginx-proxy-manager proxy host configuration
5. Verify firewall allows HTTPS (port 443)

Schema Not Persisting

# Check volume exists
docker volume ls | grep geoguessr-mcp-schemas-prod

# Inspect volume
docker volume inspect geoguessr-mcp-schemas-prod

# If missing, recreate:
docker compose -f docker-compose.prod.yml down
docker volume create geoguessr-mcp-schemas-prod
docker compose -f docker-compose.prod.yml up -d

Security Best Practices

1. Secure Environment Variables

# Ensure .env file is not world-readable
chmod 600 .env

# Never commit .env to git
# (already in .gitignore)

2. Update nginx-proxy-manager Default Credentials

After first login:

1. Go to "Users"
2. Edit the admin user
3. Change email and password
4. Enable 2FA if available

3. Configure Firewall

# Allow only necessary ports
sudo ufw allow 22/tcp   # SSH
sudo ufw allow 80/tcp   # HTTP (for Let's Encrypt)
sudo ufw allow 443/tcp  # HTTPS
sudo ufw enable

4. Regular Updates

# Update system packages
sudo apt update && sudo apt upgrade -y

# Update Docker images monthly
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

5. Monitor Access Logs

nginx-proxy-manager provides access logs:

1. Admin interface → "Hosts" → "Proxy Hosts"
2. Click on your host → "Access List" tab
3. Optionally restrict by IP addresses

Performance Optimization

1. Enable Caching in nginx-proxy-manager

Add custom nginx configuration:

# In proxy host "Advanced" tab
proxy_cache_path /tmp/cache levels=1:2 keys_zone=geoguessr_cache:10m max_size=100m inactive=60m;
proxy_cache geoguessr_cache;
proxy_cache_valid 200 10m;
proxy_cache_valid 404 1m;
add_header X-Cache-Status $upstream_cache_status;

2. Adjust Container Resources

If needed, limit resources in docker-compose.prod.yml:

services:
  geoguessr-mcp:
    # ... existing config ...
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Monitoring Tools

Check API Endpoint Status

Use the MCP tools in Claude:

Use the check_api_status() tool to see:
- All monitored endpoints
- Response times
- Schema changes
- Error rates

Container Health Metrics

# CPU and memory usage
docker stats geoguessr-mcp-server

# Detailed inspection
docker inspect geoguessr-mcp-server

Rollback Procedure

If an update causes issues:

cd /geoguessr-mcp

# Stop current version
docker compose -f docker-compose.prod.yml down

# Update .env to use previous tag
nano .env
# Change: IMAGE_TAG=v1.0.0  (or previous version)

# Restart with old version
docker compose -f docker-compose.prod.yml up -d

Getting Help

• Issues: https://github.com/yourusername/geoguessr-mcp/issues
• Logs: Always include container logs when reporting issues
• nginx-proxy-manager docs: https://nginxproxymanager.com/guide/

---

Last Updated: 2025-11-29