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**
```bash
./setup-nginx-subdomain.sh
```

**Alternative: Path-Based Routing** (requires Next.js basePath config)
```bash
./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:**
   ```bash
   ./setup-nginx-subdomain.sh
   ```

2. **Start services:**
   ```bash
   # 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"**
```bash
# Check /etc/hosts
cat /etc/hosts | grep local

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

**Issue: "502 Bad Gateway"**
```bash
# 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**
```bash
# 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`:
   ```typescript
   const nextConfig: NextConfig = {
     basePath: '/stemedb',  // ADD THIS LINE
     // ... rest of config
   };
   ```

   Edit `applications/aphoria-dashboard/next.config.ts`:
   ```typescript
   const nextConfig: NextConfig = {
     basePath: '/aphoria',  // ADD THIS LINE
     // ... rest of config
   };
   ```

2. **Run the setup script:**
   ```bash
   ./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:

```bash
# 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:**
```bash
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:**
```bash
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`