stemedb/applications/NGINX_SETUP_GUIDE.md

Nginx Proxy Setup Guide

This guide explains how to configure nginx as a reverse proxy for both StemeDB and Aphoria dashboards.

TL;DR - Quick Setup

Recommended: Subdomain Routing

./setup-nginx-subdomain.sh

Alternative: Path-Based Routing (requires Next.js basePath config)

./setup-nginx-proxy.sh

---

Option 1: Subdomain Routing (RECOMMENDED)

Pros

• ✅ Clean URLs (stemedb.local, aphoria.local)
• ✅ No Next.js configuration changes needed
• ✅ Works perfectly with Next.js App Router
• ✅ Each dashboard gets its own domain
• ✅ No asset path conflicts

Cons

• ❌ Requires /etc/hosts configuration
• ❌ Can't use single hostname like "jml"

Setup

1. Run the setup script:

   ./setup-nginx-subdomain.sh
   

2. Start services:

   # Terminal 1: Backend API (port 18180)
   cargo run --bin stemedb-api
   
   # Terminal 2: StemeDB Dashboard (port 18188)
   cd applications/stemedb-dashboard && npm run dev
   
   # Terminal 3: Aphoria Dashboard (port 18189)
   cd applications/aphoria-dashboard && npm run dev
   

3. Access dashboards:

   • StemeDB: http://stemedb.local
   • Aphoria: http://aphoria.local
   • API: http://api.local/v1/

How It Works

The script:

1. Adds entries to /etc/hosts:

   127.0.0.1 stemedb.local aphoria.local api.local
   

2. Creates 3 nginx server blocks:

   • stemedb-dashboard → proxies stemedb.local to port 18188
   • aphoria-dashboard → proxies aphoria.local to port 18189
   • stemedb-api → proxies api.local to port 18180

3. Enables sites and reloads nginx

Troubleshooting

Issue: "This site can't be reached"

# Check /etc/hosts
cat /etc/hosts | grep local

# Should see:
# 127.0.0.1 stemedb.local aphoria.local api.local

Issue: "502 Bad Gateway"

# Check if services are running
curl http://localhost:18188  # StemeDB Dashboard
curl http://localhost:18189  # Aphoria Dashboard
curl http://localhost:18180/health  # API

Issue: Nginx errors

# Check nginx logs
sudo tail -f /var/log/nginx/error.log

# Check nginx status
sudo systemctl status nginx

# Test nginx config
sudo nginx -t

---

Option 2: Path-Based Routing (REQUIRES NEXT.JS CONFIG)

Pros

• ✅ Single hostname (http://jml)
• ✅ No /etc/hosts changes needed

Cons

• ❌ Requires Next.js basePath configuration
• ❌ All assets must be prefixed with basePath
• ❌ More complex nginx rewrite rules
• ❌ Potential asset path conflicts

Setup

⚠️ WARNING: This approach requires modifying Next.js configuration and may cause issues with hot module reload (HMR) in development.

1. Update Next.js configs:

   Edit applications/stemedb-dashboard/next.config.ts:

   const nextConfig: NextConfig = {
     basePath: '/stemedb',  // ADD THIS LINE
     // ... rest of config
   };
   

   Edit applications/aphoria-dashboard/next.config.ts:

   const nextConfig: NextConfig = {
     basePath: '/aphoria',  // ADD THIS LINE
     // ... rest of config
   };
   

2. Run the setup script:

   ./setup-nginx-proxy.sh
   

3. Start services (same as above)

4. Access dashboards:

   • Default (Aphoria): http://jml
   • Aphoria: http://jml/aphoria/
   • StemeDB: http://jml/stemedb/
   • API: http://jml/v1/

How It Works

The script:

1. Creates nginx config with path-based routing
2. Uses rewrite rules to strip path prefixes before proxying
3. Proxies /_next/ assets correctly for both dashboards
4. Sets root / to redirect to /aphoria/ by default

Known Issues

Development Mode HMR: Next.js hot module reload may not work correctly with basePath in development mode. For development, prefer using direct ports (localhost:18188, localhost:18189) or subdomain routing.

Asset Loading: If assets fail to load, check browser console for 404 errors. The basePath must match the nginx location exactly.

---

Direct Port Access (No Nginx)

You can always access dashboards directly without nginx:

# Start services
cargo run --bin stemedb-api              # Terminal 1
cd applications/stemedb-dashboard && npm run dev  # Terminal 2
cd applications/aphoria-dashboard && npm run dev  # Terminal 3

# Access directly
http://localhost:18188  # StemeDB Dashboard
http://localhost:18189  # Aphoria Dashboard
http://localhost:18180  # API

This is the simplest approach for local development and avoids nginx complexity entirely.

---

Comparison Table

Feature	Subdomain	Path-Based	Direct Ports
Setup complexity	Medium	High	None
Next.js changes	None	Required	None
Clean URLs	✅	⚠️	❌
HMR in dev	✅	⚠️	✅
Production-ready	✅	✅	❌
Works with "jml" hostname	❌	✅	❌
Multiple projects	✅	⚠️	✅

Recommendation

For local development: Use Direct Ports (no nginx)

• Simplest setup
• Perfect for development
• No configuration needed

For shared environments: Use Subdomain Routing

• Clean URLs
• No Next.js configuration changes
• Production-ready
• Easy to add more services

Avoid: Path-based routing unless you have specific requirements for single-hostname access.

---

Cleanup

Remove subdomain setup:

sudo rm /etc/nginx/sites-enabled/stemedb-dashboard
sudo rm /etc/nginx/sites-enabled/aphoria-dashboard
sudo rm /etc/nginx/sites-enabled/stemedb-api
sudo rm /etc/nginx/sites-available/stemedb-dashboard
sudo rm /etc/nginx/sites-available/aphoria-dashboard
sudo rm /etc/nginx/sites-available/stemedb-api
sudo sed -i '/stemedb.local/d' /etc/hosts
sudo sed -i '/aphoria.local/d' /etc/hosts
sudo sed -i '/api.local/d' /etc/hosts
sudo nginx -t && sudo systemctl reload nginx

Remove path-based setup:

sudo rm /etc/nginx/sites-enabled/stemedb
sudo rm /etc/nginx/sites-available/stemedb
sudo nginx -t && sudo systemctl reload nginx

# Also remove basePath from next.config.ts files if added

---

Questions?

• Which should I use? → Subdomain routing (or direct ports for dev)
• Can I use both? → No, they conflict. Choose one.
• What about production? → Use subdomain routing with proper domain names
• What if I don't have nginx? → Install: sudo apt install nginx