scoffer/PORT_CONFIGURATION.md

# Port Configuration Guide

## Overview

The Docker Compose setup now supports configurable ports through environment variables. This allows you to customize which host ports are used for each service without modifying the docker-compose.yml file.

## Available Port Variables

| Service | Environment Variable | Default Port | Description |
|---------|---------------------|--------------|-------------|
| Frontend | `FRONTEND_PORT` | 3000 | React app served by nginx |
| Backend | `BACKEND_PORT` | 5000 | Node.js API server |
| MongoDB | `MONGODB_PORT` | 27017 | MongoDB database |
| Mongo Express | `MONGO_EXPRESS_PORT` | 8081 | Database admin interface |

## Usage Examples

### Default Configuration
If no environment variables are set, the services will use default ports:
```bash
docker-compose up -d
```
- Frontend: http://localhost:3000
- Backend: http://localhost:5000
- MongoDB: localhost:27017
- Mongo Express: http://localhost:8081

### Custom Port Configuration

#### Option 1: Environment Variables
```bash
export FRONTEND_PORT=8080
export BACKEND_PORT=3001
export MONGODB_PORT=27018
export MONGO_EXPRESS_PORT=8082

docker-compose up -d
```

#### Option 2: .env File
Create or update your `.env` file:
```bash
# Port Configuration
FRONTEND_PORT=8080
BACKEND_PORT=3001
MONGODB_PORT=27018
MONGO_EXPRESS_PORT=8082

# Other configuration...
REACT_APP_API_URL=http://localhost:3001/api
JWT_SECRET=your-secret-key
```

Then run:
```bash
docker-compose up -d
```

#### Option 3: Inline with Docker Compose
```bash
FRONTEND_PORT=8080 BACKEND_PORT=3001 docker-compose up -d
```

## Common Scenarios

### Development on Different Ports
If you have other services running on default ports:
```bash
# .env file
FRONTEND_PORT=3001
BACKEND_PORT=5001
MONGODB_PORT=27018
MONGO_EXPRESS_PORT=8082
REACT_APP_API_URL=http://localhost:5001/api
```

### Production Server with Port Restrictions
If your server has specific port requirements:
```bash
# .env file
FRONTEND_PORT=80
BACKEND_PORT=8000
MONGODB_PORT=27017
MONGO_EXPRESS_PORT=8081
REACT_APP_API_URL=https://your-domain.com/api
```

### Multiple Environments on Same Server
For running multiple instances (dev/staging/prod):

**Development (.env.dev)**:
```bash
FRONTEND_PORT=3000
BACKEND_PORT=5000
MONGODB_PORT=27017
MONGO_EXPRESS_PORT=8081
REACT_APP_API_URL=http://localhost:5000/api
```

**Staging (.env.staging)**:
```bash
FRONTEND_PORT=3001
BACKEND_PORT=5001
MONGODB_PORT=27018
MONGO_EXPRESS_PORT=8082
REACT_APP_API_URL=https://staging.your-domain.com/api
```

**Production (.env.prod)**:
```bash
FRONTEND_PORT=80
BACKEND_PORT=8000
MONGODB_PORT=27019
MONGO_EXPRESS_PORT=8083
REACT_APP_API_URL=https://your-domain.com/api
```

Deploy with specific environment:
```bash
# Copy the desired environment file
cp .env.staging .env
docker-compose up -d

# Or specify directly
docker-compose --env-file .env.staging up -d
```

## Important Notes

### Internal Container Ports
The environment variables only affect **host ports** (external access). Internal container ports remain the same:
- Frontend container: Always port 80 (nginx)
- Backend container: Always port 5000 (Node.js)
- MongoDB container: Always port 27017
- Mongo Express: Always port 8081

### API URL Configuration
When changing the backend port, remember to update `REACT_APP_API_URL`:
```bash
# If backend runs on port 3001
BACKEND_PORT=3001
REACT_APP_API_URL=http://localhost:3001/api
```

### Port Conflicts
Check for port conflicts before starting:
```bash
# Check if ports are in use
netstat -tulpn | grep :3000
netstat -tulpn | grep :5000
netstat -tulpn | grep :27017
netstat -tulpn | grep :8081

# Or use lsof
lsof -i :3000
lsof -i :5000
```

### Firewall Considerations
Ensure your firewall allows traffic on the configured ports:
```bash
# Ubuntu/Debian
sudo ufw allow 3000
sudo ufw allow 5000

# CentOS/RHEL
sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --add-port=5000/tcp --permanent
sudo firewall-cmd --reload
```

## Troubleshooting

### Port Already in Use
```bash
Error: bind: address already in use
```
**Solution**: Change the port or stop the conflicting service:
```bash
# Find what's using the port
lsof -i :3000

# Kill the process or change your port
FRONTEND_PORT=3001 docker-compose up -d
```

### Frontend Can't Connect to Backend
If you change the backend port, update the API URL:
```bash
# Wrong - API URL doesn't match backend port
BACKEND_PORT=3001
REACT_APP_API_URL=http://localhost:5000/api

# Correct
BACKEND_PORT=3001
REACT_APP_API_URL=http://localhost:3001/api
```

### Database Connection Issues
The backend connects to MongoDB using the service name `mongodb:27017` (internal). The `MONGODB_PORT` variable only affects external access.

## Quick Reference

### Start with Custom Ports
```bash
# Quick start with custom ports
FRONTEND_PORT=8080 BACKEND_PORT=3001 docker-compose up -d

# Check services
docker-compose ps

# View logs
docker-compose logs -f
```

### Reset to Defaults
```bash
# Remove custom environment variables
unset FRONTEND_PORT BACKEND_PORT MONGODB_PORT MONGO_EXPRESS_PORT

# Or remove from .env file and restart
docker-compose down
docker-compose up -d
```