honey-be/VPS_DEPLOYMENT_SUMMARY.md

VPS Deployment Summary

✅ Compatibility Check

Backend (lottery-be)

✅ Dockerfile: Production-ready

• Multi-stage build (Maven → JRE)
• Exposes port 8080 (internal only)
• HTTP only (no HTTPS configuration)
• Binds to 0.0.0.0 by default (Spring Boot default)
• Graceful shutdown supported

✅ Configuration: Externalized

• Database connection via environment variables
• Avatar storage path configurable (APP_AVATAR_STORAGE_PATH)
• All sensitive data via .env file
• CORS configured via FRONTEND_URL env var

✅ File Uploads: Persistent storage ready

• Avatar path configurable and mountable as Docker volume
• Uses filesystem (not ephemeral storage)
• Path: /app/data/avatars (configurable)

✅ Networking: Internal Docker network

• No ports exposed to host in production compose
• Accessible only via Nginx reverse proxy
• Uses Docker bridge network

✅ Production Readiness:

• Logging to stdout/stderr (Docker logs)
• Health checks configured
• Graceful shutdown
• No dev-only features enabled

Frontend (lottery-fe)

✅ Build Mode: Production-ready

• npm run build creates static files in dist/
• Vite production build configured

✅ API Base URL: Configurable

• Uses relative URLs in production (empty string)
• Falls back to localhost:8080 in development
• Can be overridden via VITE_API_BASE_URL env var

✅ Docker Usage: Optional

• Dockerfile exists but not required for VPS
• Static files can be served directly by Nginx

✅ Telegram Mini App: Ready

• Works under HTTPS
• No localhost assumptions
• Uses relative API URLs

📋 Required Changes Made

Frontend Changes

1. API Base URL Configuration (src/api.js, src/auth/authService.js, src/services/gameWebSocket.js, src/utils/remoteLogger.js)
   • Changed to use relative URLs in production
   • Falls back to localhost:8080 only in development
   • Pattern: import.meta.env.VITE_API_BASE_URL || (import.meta.env.PROD ? "" : "http://localhost:8080")

Backend Changes

✅ No changes required - Already production-ready!

📁 New Files Created

1. docker-compose.prod.yml - Production Docker Compose configuration

   • No port exposure to host
   • Persistent volumes for database and avatars
   • Health checks configured
   • Internal Docker network

2. nginx.conf.template - Nginx reverse proxy configuration

   • HTTPS termination
   • Frontend static file serving
   • Backend API proxying (/api/*)
   • WebSocket support (/ws)
   • Avatar file serving (/avatars/*)
   • Security headers
   • Gzip compression

3. DEPLOYMENT_GUIDE.md - Comprehensive deployment guide

   • Step-by-step instructions
   • Troubleshooting section
   • Maintenance commands
   • Security checklist

🚀 Deployment Steps Overview

1. VPS Setup: Install Docker, Docker Compose, Nginx, Certbot
2. Directory Structure: Create /opt/app with subdirectories
3. Backend Deployment: Copy files, create secret file at /run/secrets/lottery-config.properties, build and start
4. Frontend Deployment: Build locally, copy dist/ to VPS
5. Nginx Configuration: Copy template, update domain, link config
6. SSL Setup: Obtain Let's Encrypt certificate
7. Telegram Webhook: Update webhook URL
8. Verification: Test all endpoints and functionality

🔧 Configuration Required

Backend Secret File (/run/secrets/lottery-config.properties)

All configuration is stored in a mounted secret file. See lottery-config.properties.template for the complete template.

Required variables:

• SPRING_DATASOURCE_URL
• SPRING_DATASOURCE_USERNAME
• SPRING_DATASOURCE_PASSWORD
• TELEGRAM_BOT_TOKEN
• TELEGRAM_CHANNEL_CHECKER_BOT_TOKEN
• TELEGRAM_FOLLOW_TASK_CHANNEL_ID
• FRONTEND_URL

Optional variables:

• APP_AVATAR_STORAGE_PATH
• APP_AVATAR_PUBLIC_BASE_URL
• APP_SESSION_MAX_ACTIVE_PER_USER
• APP_SESSION_CLEANUP_BATCH_SIZE
• APP_SESSION_CLEANUP_MAX_BATCHES
• GEOIP_DB_PATH

Note: The MySQL container also needs DB_PASSWORD and DB_ROOT_PASSWORD as environment variables (should match SPRING_DATASOURCE_PASSWORD).

📂 Final Directory Structure on VPS

/opt/app/
├── backend/
│   ├── Dockerfile
│   ├── docker-compose.prod.yml
│   ├── lottery-config.properties.template
│   └── [source files]
├── frontend/
│   └── dist/          (Vite production build)
├── nginx/
│   └── nginx.conf
├── data/
│   └── avatars/       (persistent uploads)
└── mysql/
    └── data/          (persistent DB storage)

/run/secrets/
└── lottery-config.properties  (mounted secret file)

✅ Verification Checklist

Before going live:

• All environment variables set in .env
• Backend containers running (docker ps)
• Frontend dist/ folder populated
• Nginx configuration tested (nginx -t)
• SSL certificate installed and valid
• Telegram webhook updated
• Health checks passing (/actuator/health)
• Frontend loads in browser
• API calls work (check browser console)
• WebSocket connects (game updates work)
• Avatar uploads work
• Database persists data (restart test)

🔒 Security Notes

• Backend port 8080 not exposed to host
• MySQL port 3306 not exposed to host
• HTTPS enforced (HTTP → HTTPS redirect)
• Strong passwords required
• .env file permissions restricted
• Firewall recommended (UFW)

📝 Next Steps

1. Review DEPLOYMENT_GUIDE.md for detailed instructions
2. Prepare your VPS (Ubuntu recommended)
3. Follow the step-by-step guide
4. Test thoroughly before going live
5. Set up monitoring and backups

---

Status: ✅ Ready for VPS Deployment Last Updated: 2026-01-24