Church-Music/legacy-site/documentation/md-files/PORTS_LOCKED.md

# 🔒 PORT CONFIGURATION - PERMANENTLY LOCKED

## Church Music Database Ports

**DO NOT CHANGE THESE PORTS**

### Production Ports (LOCKED)

- **Backend API:** `8080` (Gunicorn + Flask)
- **Frontend:** `5100` (Node serve)
- **HTTPS Proxy:** `443` (Nginx → 8080/5100)

### Port Status

```bash
# Check ports
sudo lsof -i :8080 -i :5100 | grep LISTEN

# Expected output:
# gunicorn  ... *:8080 (LISTEN)  - Backend
# node      ... *:5100 (LISTEN)  - Frontend
```

## Service Management

### Start Services (Correct Way)

```bash
sudo systemctl start church-music-backend church-music-frontend
```

### Stop Services

```bash
sudo systemctl stop church-music-backend church-music-frontend
```

### Restart Services

```bash
sudo systemctl restart church-music-backend church-music-frontend
```

### Check Status

```bash
sudo systemctl status church-music-backend church-music-frontend
```

## Troubleshooting

### Port 8080 In Use

```bash
# Kill any rogue process
sudo lsof -ti:8080 | xargs -r sudo kill -9
sudo systemctl restart church-music-backend
```

### Port 5100 In Use  

```bash
# Kill any rogue process
sudo lsof -ti:5100 | xargs -r sudo kill -9
sudo systemctl restart church-music-frontend
```

### Both Ports Blocked

```bash
# Nuclear option - kill all and restart
sudo pkill -9 gunicorn
sudo pkill -9 serve
sleep 2
sudo systemctl restart church-music-backend church-music-frontend
```

## Configuration Files

### Backend Service

`/etc/systemd/system/church-music-backend.service`

- Binds to: `127.0.0.1:8080`
- Workers: 2
- Auto-restart: Yes

### Frontend Service

`/etc/systemd/system/church-music-frontend.service`

- Binds to: `0.0.0.0:5100`
- Serves: `/media/pts/Website/Church_HOP_MusicData/frontend/build`
- Auto-restart: Yes

### Nginx Proxy

`/etc/nginx/sites-enabled/church-music*`

- Proxies `https://houseofprayer.ddns.net/api/*` → `http://127.0.0.1:8080/api/*`
- Proxies `https://houseofprayer.ddns.net/*` → `http://127.0.0.1:5100/*`

## Architecture

```
Internet (HTTPS :443)
        ↓
    Nginx Reverse Proxy
        ↓
    ┌───────────────┬────────────────┐
    ↓               ↓                ↓
Frontend        Backend API      Database
(Port 5100)     (Port 8080)    (PostgreSQL :5432)
React Build     Flask/Gunicorn  
```

## DO NOT

- ❌ Change ports 8080 or 5100
- ❌ Run manual gunicorn/serve on different ports
- ❌ Use ports 3000, 5000, 5965, or any other port
- ❌ Run services outside of systemd
- ❌ Modify port configuration without updating ALL of:
  - Systemd service files
  - Nginx configuration
  - Backend configuration
  - Frontend API base URL

## Auto-Start on Boot

Services are enabled to start automatically:

```bash
sudo systemctl is-enabled church-music-backend church-music-frontend
# Both should show: enabled
```

---
**Last Verified:** December 17, 2025 22:29 CST
**Status:** ✅ LOCKED AND OPERATIONAL