Deployment

jDuel deploys to an Ubuntu EC2 instance using SystemD + Nginx. No Docker, no CI/CD — manual deploy via deploy.sh.

deploy.sh Walkthrough

The script runs 8 steps sequentially (set -e — fails fast on any error):

Downtime: Backend is stopped during the entire deploy (steps 1-6). Frontend static files are served by Nginx throughout, but API/WebSocket calls fail during this window.

Rolling Back a Bad Deploy

# 1. Revert to last known good commit
git log --oneline -5           # Find the good commit
git checkout <good-commit>     # Detach HEAD at that commit

# 2. Re-run deploy
./deploy.sh

# 3. After verifying, return to main
git checkout main

If only the backend is broken:

sudo systemctl restart jduel-backend
journalctl -u jduel-backend -n 50    # Check what went wrong

If only the frontend is broken:

cd frontend && npm run build
sudo cp -r dist /var/www/jduel-frontend/
sudo systemctl reload nginx

SystemD Service Management

# Status and control
sudo systemctl status jduel-backend
sudo systemctl start jduel-backend
sudo systemctl stop jduel-backend
sudo systemctl restart jduel-backend

# Logs
journalctl -u jduel-backend -f          # Real-time tail
journalctl -u jduel-backend -n 100      # Last 100 lines
journalctl -u jduel-backend -b          # Since last boot
journalctl -u jduel-backend --since "1 hour ago"

Service file: /etc/systemd/system/jduel-backend.service

Key settings:

• •Restart=always + RestartSec=3 — auto-restart on crash
• •Environment=PYTHONUNBUFFERED=1 — real-time log output
• •Optional Environment=CUDA_VISIBLE_DEVICES= — disable CUDA to save ~2GB RAM

Nginx

sudo nginx -t                    # Test config syntax (always do this first)
sudo systemctl reload nginx      # Graceful reload (zero downtime)
sudo systemctl restart nginx     # Full restart (brief downtime)
sudo tail -f /var/log/nginx/error.log

Config file: /etc/nginx/sites-available/jduel

Reload vs restart: Use reload for config changes. Use restart only if reload fails or after major changes.

Health Checks

# Backend health
curl http://127.0.0.1:8000/health

# From outside (through Nginx)
curl https://jduel.xyz/health

The /health endpoint returns 200 when the FastAPI server is running. It does not verify NLP model loading — the app serves requests immediately, and model loading happens in the background during lifespan startup.

Memory

For t3.small (2GB): Must disable CUDA. For t3.medium (4GB): Safe with CUDA disabled, tight with CUDA.

Common Issues

OOM on small instances: Add Environment=CUDA_VISIBLE_DEVICES= to the service file to disable CUDA and save ~2GB.

Backend won't start:

which uv                                   # Verify uv path matches service file
journalctl -u jduel-backend -n 50          # Check error
sudo lsof -i :8000                         # Port already in use?

WebSocket 502 errors: Nginx config missing Upgrade/Connection headers or timeouts too low. Check /etc/nginx/sites-available/jduel.

Certificate renewal failed: Ensure port 80 is open (certbot HTTP challenge), DNS points to server IP, and Nginx is running.

Key Files