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:

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

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:

# 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:

docker-compose up -d

Option 3: Inline with Docker Compose

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:

# .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:

# .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):

FRONTEND_PORT=3000
BACKEND_PORT=5000
MONGODB_PORT=27017
MONGO_EXPRESS_PORT=8081
REACT_APP_API_URL=http://localhost:5000/api

Staging (.env.staging):

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):

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:

# 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:

# 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:

# 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:

# 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

Error: bind: address already in use

Solution: Change the port or stop the conflicting service:

# 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:

# 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

# 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

# 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