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