docker_ldap_testing/PORT_CONFIGURATION.md

Port Configuration Guide

This guide explains how to configure custom ports for your LDAP Docker environment to avoid conflicts with other services.

Quick Start

To change ports, simply edit the .env file:

# Edit .env file
LDAP_PORT=20389
LDAPS_PORT=20636
PHPLDAPADMIN_PORT=8080

Then restart:

make down && make start

That's it! All scripts and tools will automatically use your custom ports.

---

Why Custom Ports?

You might want to use custom ports if:

• You have another LDAP server running on standard ports (389/636)
• Port 389 requires root/admin privileges
• You're running multiple LDAP environments simultaneously
• Your organization has specific port requirements

Files Involved

The port configuration system uses these files:

1. .env - Your Configuration (Edit This!)

LDAP_PORT=20389          # Your custom LDAP port
LDAPS_PORT=20636         # Your custom LDAPS port
PHPLDAPADMIN_PORT=8080   # Web admin interface port

2. docker-compose.yml - Uses Environment Variables

ports:
  - "${LDAP_PORT:-389}:389"      # Host:Container mapping
  - "${LDAPS_PORT:-636}:636"

The ${LDAP_PORT:-389} syntax means:

• Use $LDAP_PORT if set in .env
• Otherwise use default 389

3. Scripts - Auto-detect Ports

All Python scripts and Makefile commands read from .env automatically:

• scripts/cli.py
• scripts/ldapsearch_helper.sh
• examples/simple_auth.py
• Makefile

How to Change Ports

Method 1: Edit .env File (Recommended)

1. Edit .env:

   vim .env  # or your favorite editor
   

2. Change the port values:

   LDAP_PORT=20389
   LDAPS_PORT=20636
   

3. Restart the containers:

   make down && make start
   

4. Verify:

   docker-compose ps
   # Should show 0.0.0.0:20389->389/tcp
   

Method 2: Environment Variables (Temporary)

For one-time use without modifying .env:

LDAP_PORT=30389 LDAPS_PORT=30636 docker-compose up -d

Method 3: Create .env.local (Advanced)

For personal overrides without modifying the main .env:

# Create .env.local (git-ignored)
echo "LDAP_PORT=12389" > .env.local
echo "LDAPS_PORT=12636" >> .env.local

# Docker Compose will merge both files
docker-compose up -d

Testing with Custom Ports

Automatic - Use Our Tools

All our tools automatically detect your ports from .env:

# These all work automatically with your custom ports
make test-users
make test-connection
uv run python examples/simple_auth.py

Generate ldapsearch Commands

Use our helper script to generate commands with your ports:

./scripts/ldapsearch_helper.sh

Output includes commands like:

# List all users
ldapsearch -H ldap://localhost:20389 \
  -D "cn=admin,dc=testing,dc=local" \
  -w admin_password \
  -b "ou=people,dc=testing,dc=local" \
  "(objectClass=inetOrgPerson)" \
  uid cn mail

Manual ldapsearch Commands

Replace 389 with your LDAP_PORT and 636 with your LDAPS_PORT:

# Standard LDAP (unencrypted)
ldapsearch -H ldap://localhost:20389 \
  -D "cn=admin,dc=testing,dc=local" \
  -w admin_password \
  -b "dc=testing,dc=local"

# LDAPS (SSL/TLS)
ldapsearch -H ldaps://localhost:20636 \
  -D "cn=admin,dc=testing,dc=local" \
  -w admin_password \
  -b "dc=testing,dc=local"

# Search for specific user
ldapsearch -H ldap://localhost:20389 \
  -D "cn=admin,dc=testing,dc=local" \
  -w admin_password \
  -b "dc=testing,dc=local" \
  "(uid=jdoe)"

# Test user authentication
ldapsearch -H ldap://localhost:20389 \
  -D "uid=jdoe,ou=people,dc=testing,dc=local" \
  -w password123 \
  -b "dc=testing,dc=local" \
  "(uid=jdoe)"

Using Python

import os
from ldap3 import Server, Connection

# Automatically uses LDAP_PORT from environment
port = os.environ.get('LDAP_PORT', '389')
server = Server(f'ldap://localhost:{port}')
conn = Connection(server, 
                  user='cn=admin,dc=testing,dc=local',
                  password='admin_password',
                  auto_bind=True)

conn.search('dc=testing,dc=local', '(objectClass=*)')
print(f"Connected on port {port}")
conn.unbind()

Common Port Configurations

Development (Unprivileged Ports)

LDAP_PORT=20389
LDAPS_PORT=20636
PHPLDAPADMIN_PORT=8080

Testing (High Ports)

LDAP_PORT=30389
LDAPS_PORT=30636
PHPLDAPADMIN_PORT=8090

Multiple Environments

# Environment 1 (.env)
LDAP_PORT=20389
LDAPS_PORT=20636

# Environment 2 (separate directory or .env.local)
LDAP_PORT=21389
LDAPS_PORT=21636

Troubleshooting

Port Already in Use

Error: Bind for 0.0.0.0:20389 failed: port is already allocated

Check what's using the port:

lsof -i :20389
# or
netstat -an | grep 20389

Solutions:

1. Stop the conflicting service
2. Choose a different port in .env
3. Use make down to stop this LDAP server first

Scripts Not Using Custom Ports

Problem: Scripts still connect to port 389

Solution: Ensure .env is loaded:

1. Check .env exists:

   ls -la .env
   

2. Verify ports are set:

   grep LDAP_PORT .env
   

3. Reload environment:

   source .env  # For bash scripts
   make down && make start  # Restart containers
   

Docker Compose Not Reading .env

Problem: Containers still on default ports

Check:

# View what Docker Compose sees
docker-compose config | grep -A2 ports

Solution:

# Ensure .env is in project root
pwd  # Should be ldap_docker/
ls .env  # Should exist

# Force reload
docker-compose down
docker-compose up -d

Can't Connect After Port Change

Verify containers are running on correct ports:

docker-compose ps
# Should show: 0.0.0.0:20389->389/tcp

Test connectivity:

# Test if port is listening
nc -zv localhost 20389

# Test LDAP response
ldapsearch -H ldap://localhost:20389 -x -b "" -s base

Check logs:

make logs
# Look for: "slapd starting"

Port Reference Table

Service	Default Port	Docker Internal Port	Configurable Via
LDAP	389	389	LDAP_PORT in .env
LDAPS	636	636	LDAPS_PORT in .env
phpLDAPadmin	8080	80	PHPLDAPADMIN_PORT in .env

Note: The "Docker Internal Port" (right side of mapping) never changes. Only the host port (left side) is configurable.

Advanced: Port Mapping Explained

Docker port mapping format: HOST:CONTAINER

ports:
  - "20389:389"

This means:

• 20389 = Port on your Mac (accessible via localhost:20389)
• 389 = Port inside the Docker container (LDAP's standard port)

The container always listens on 389 internally. We just map it to 20389 externally.

Testing Multiple Configurations

Run multiple LDAP servers simultaneously:

# Terminal 1: First instance
cd ldap_docker_1
echo "LDAP_PORT=20389" > .env
echo "LDAPS_PORT=20636" >> .env
make start

# Terminal 2: Second instance
cd ldap_docker_2
echo "LDAP_PORT=21389" > .env
echo "LDAPS_PORT=21636" >> .env
make start

# Now you have two LDAP servers running!
ldapsearch -H ldap://localhost:20389 ...  # Server 1
ldapsearch -H ldap://localhost:21389 ...  # Server 2

Best Practices

1. Use .env for configuration - Don't hardcode ports in scripts
2. Document your ports - Add comments in .env explaining your choices
3. Use unprivileged ports - Ports above 1024 don't require root
4. Avoid common ports - Skip 8080, 3000, 5000 (often used by other tools)
5. Be consistent - If LDAP is 20389, make LDAPS 20636 (same prefix)

Integration Examples

Configure Your Application

After changing ports, update your application's LDAP configuration:

# Django settings.py
AUTH_LDAP_SERVER_URI = "ldap://localhost:20389"

# Flask
LDAP_HOST = "localhost"
LDAP_PORT = 20389

# Environment variable
export LDAP_URL="ldap://localhost:20389"

Using with Docker Networks

If your application is also in Docker:

# Your app's docker-compose.yml
services:
  your-app:
    environment:
      LDAP_URL: "ldap://ldap-server:389"  # Use container name and internal port
    networks:
      - ldap_docker_ldap-network  # Connect to LDAP network

networks:
  ldap_docker_ldap-network:
    external: true

Quick Reference

# View current configuration
cat .env | grep PORT

# Generate ldapsearch commands
./scripts/ldapsearch_helper.sh

# Test connection on custom port
make test-connection

# Check what ports containers are using
docker-compose ps

# Change ports (example)
echo "LDAP_PORT=12389" > .env
echo "LDAPS_PORT=12636" >> .env
make down && make start

# Verify new ports work
make test-users

Summary

To use custom ports:

1. Edit LDAP_PORT and LDAPS_PORT in .env
2. Run make down && make start
3. All tools automatically use your new ports!

Need ldapsearch commands?

• Run ./scripts/ldapsearch_helper.sh
• Or manually replace 389 → your LDAP_PORT, 636 → your LDAPS_PORT

That's it! The port configuration system is designed to be simple and automatic.

---

See Also:

• README.md - Full documentation
• GETTING_STARTED.md - Setup guide
• QUICKREF.md - Command reference