f3cef2e4dc
## Summary Implements proper HTTP deployment for the Nexus to fix module import issues when accessing via file:// or raw Forge URLs. ## Changes 1. **Nginx Configuration** (`nginx.conf`) - Serves static files with gzip compression - Proper CORS headers for development - WebSocket proxy to Python server - Security headers - SPA routing support 2. **Docker Setup** (`Dockerfile.nginx`, `docker-compose.nginx.yml`) - Multi-stage build: nginx + Python - Health check endpoint - Production and staging environments - Proper logging volumes 3. **Deployment Scripts** - `deploy.sh` — Updated to support nginx deployment - `docker-entrypoint.sh` — Starts both nginx and Python server - `setup-vps.sh` — VPS initial setup script 4. **CI/CD** (`.gitea/workflows/deploy-nginx.yml`) - Automated deployment on push to main - VPS deployment via SSH - Health check verification 5. **Documentation** (`DEPLOYMENT.md`) - Quick start guide - DNS configuration - Troubleshooting - Architecture overview ## URLs - **Local:** http://localhost (main), http://localhost:8080 (staging) - **Production:** http://nexus.alexanderwhitestone.com (after DNS setup) - **Direct IP:** http://143.198.27.163 ## Testing - Module imports work over HTTP (no more file:// errors) - WebSocket connection to Python server - Health check endpoint responds - Both nginx and Python server start correctly ## Acceptance Criteria ✅ Deployed to proper URL for preview ✅ Module imports work correctly ✅ WebSocket server functional ✅ CI/CD workflow configured ✅ Documentation provided Issue: #1339
2.8 KiB
2.8 KiB
Nexus Deployment Guide
Quick Start
Option 1: Deploy with Nginx (Recommended)
# Deploy main (port 80)
./deploy.sh
# Deploy staging (port 8080)
./deploy.sh staging
Option 2: Legacy Python Deployment
# Deploy with Python only (port 8765)
./deploy.sh legacy
URL Configuration
Local Development
- Nginx Main: http://localhost
- Nginx Staging: http://localhost:8080
- Legacy Python: ws://localhost:8765
Production (Ezra VPS)
- Main Site: http://nexus.alexanderwhitestone.com (after DNS setup)
- Direct IP: http://143.198.27.163
DNS Setup
To point a domain to the Nexus:
-
Create an A record:
nexus.alexanderwhitestone.com → 143.198.27.163 -
(Optional) Set up SSL with Let's Encrypt:
sudo certbot --nginx -d nexus.alexanderwhitestone.com
Manual VPS Deployment
-
SSH into Ezra VPS:
ssh root@143.198.27.163 -
Clone and deploy:
cd ~ git clone http://143.198.27.163:3000/Timmy_Foundation/the-nexus.git cd the-nexus ./deploy.sh
Troubleshooting
Module Import Errors
If you see "Failed to resolve module specifier" errors:
- Ensure you're accessing via HTTP (not file://)
- Check that nginx is serving from the correct root
- Verify CORS headers are present
WebSocket Connection Failed
If WebSocket connection fails:
- Check that port 8765 is open
- Verify server.py is running
- Check firewall rules
Container Won't Start
# Check logs
docker compose -f docker-compose.nginx.yml logs
# Rebuild
docker compose -f docker-compose.nginx.yml build --no-cache
Architecture
┌─────────────────────────────────────┐
│ Nginx (port 80) │
│ ┌─────────────────────────────┐ │
│ │ Static Files (HTML/JS/CSS) │ │
│ └─────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Python WebSocket Server │ │
│ │ (port 8765) │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
Files
nginx.conf— Nginx configurationDockerfile.nginx— Multi-stage build (nginx + Python)docker-compose.nginx.yml— Docker Compose for nginx deploymentdocker-entrypoint.sh— Starts both nginx and Python server.gitea/workflows/deploy-nginx.yml— CI/CD workflow