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
109 lines
2.8 KiB
Markdown
109 lines
2.8 KiB
Markdown
# Nexus Deployment Guide
|
|
|
|
## Quick Start
|
|
|
|
### Option 1: Deploy with Nginx (Recommended)
|
|
|
|
```bash
|
|
# Deploy main (port 80)
|
|
./deploy.sh
|
|
|
|
# Deploy staging (port 8080)
|
|
./deploy.sh staging
|
|
```
|
|
|
|
### Option 2: Legacy Python Deployment
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
1. Create an A record:
|
|
```
|
|
nexus.alexanderwhitestone.com → 143.198.27.163
|
|
```
|
|
|
|
2. (Optional) Set up SSL with Let's Encrypt:
|
|
```bash
|
|
sudo certbot --nginx -d nexus.alexanderwhitestone.com
|
|
```
|
|
|
|
## Manual VPS Deployment
|
|
|
|
1. SSH into Ezra VPS:
|
|
```bash
|
|
ssh root@143.198.27.163
|
|
```
|
|
|
|
2. Clone and deploy:
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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 configuration
|
|
- `Dockerfile.nginx` — Multi-stage build (nginx + Python)
|
|
- `docker-compose.nginx.yml` — Docker Compose for nginx deployment
|
|
- `docker-entrypoint.sh` — Starts both nginx and Python server
|
|
- `.gitea/workflows/deploy-nginx.yml` — CI/CD workflow
|