docker_ldap_testing/GETTING_STARTED.md

Getting Started with LDAP Docker

Welcome! This guide will help you get your LDAP development server up and running in just a few minutes.

What is This?

LDAP Docker is a ready-to-use OpenLDAP server for development and testing. It comes pre-configured with:

• ✅ SSL/TLS support (LDAPS)
• ✅ Test users and groups
• ✅ Web-based admin interface
• ✅ Easy certificate management
• ✅ Simple Python CLI tools

Perfect for testing applications that need LDAP authentication without setting up a complex infrastructure.

Prerequisites

You'll need these installed on your Mac:

1. Docker or Rancher Desktop (for running containers)

   • Rancher Desktop: https://rancherdesktop.io/ (recommended for Mac)
   • Or Docker Desktop: https://www.docker.com/products/docker-desktop

2. Python 3.9+ (usually pre-installed on Mac)

   python3 --version
   

3. UV Package Manager (optional but recommended)

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

Quick Start (5 Minutes)

Option 1: Automated Setup (Easiest)

Run the quick start script that will guide you through everything:

./quickstart.sh

This interactive script will:

1. Check all prerequisites
2. Install UV (if you want)
3. Generate SSL certificates
4. Start the LDAP server
5. Verify everything works

Option 2: Manual Setup (Step by Step)

If you prefer to understand each step:

# 1. Install Python dependencies
make install

# 2. Generate SSL certificates
make certs-generate

# 3. Start the LDAP server
make start

# 4. Test the connection
make test-connection

That's it! Your LDAP server is now running.

Using Your Own Dev-CA Certificates

Since you mentioned you maintain a local dev-ca, here's how to use your own certificates:

# Instead of 'make certs-generate', copy your certificates:
cp /path/to/your/dev-ca/ca-cert.pem certs/ca.crt
cp /path/to/your/dev-ca/ldap-server.crt certs/server.crt
cp /path/to/your/dev-ca/ldap-server.key certs/server.key

# Set proper permissions
chmod 644 certs/ca.crt certs/server.crt
chmod 600 certs/server.key

# Then start the server
make start

Important: Your server certificate should be issued for hostname ldap.testing.local or include it as a Subject Alternative Name (SAN).

Accessing Your LDAP Server

Once running, you can access:

Service	URL	Purpose
LDAP	ldap://localhost:389	Standard LDAP (unencrypted)
LDAPS	ldaps://localhost:636	Secure LDAP with SSL/TLS
Admin UI	http://localhost:8080	Web interface (phpLDAPadmin)

Login Credentials

• Admin DN: cn=admin,dc=testing,dc=local
• Password: admin_password

Test Users (All use password: password123)

• jdoe - John Doe (jdoe@testing.local)
• jsmith - Jane Smith (jsmith@testing.local)
• testuser - Test User (testuser@testing.local)
• admin - Admin User (admin@testing.local)

Verify Everything Works

Test 1: List all users

make test-users

You should see output like:

Found 4 user(s):

  - Admin User: admin (admin@testing.local)
  - John Doe: jdoe (jdoe@testing.local)
  - Jane Smith: jsmith (jsmith@testing.local)
  - Test User: testuser (testuser@testing.local)

Test 2: Try the web interface

Open http://localhost:8080 in your browser and login with:

• Login DN: cn=admin,dc=testing,dc=local
• Password: admin_password

Test 3: Run the example script

python examples/simple_auth.py

This authenticates user jdoe and displays their information.

Common Commands

# Server management
make start          # Start LDAP server
make stop           # Stop LDAP server
make restart        # Restart LDAP server
make logs           # View logs (live)
make status         # Check if running

# Testing
make test-users     # List all users
make test-auth      # Test authentication
make test-all       # Run all tests

# Maintenance
make clean          # Clean build artifacts
make down           # Stop and remove containers

Next Steps

Now that your LDAP server is running, you can:

1. Integrate with Your Application

   • See examples/README.md for code samples
   • Point your app to ldap://localhost:389

2. Add Custom Users

   • Edit ldif/01-users.ldif
   • Run make down-volumes && make start to reload

3. Configure for Your Use Case

   • Edit docker-compose.yml for custom settings
   • See .env.example for environment variables

4. Learn More

   • README.md - Full documentation
   • QUICKREF.md - Command reference
   • certs/README.md - Certificate management
   • examples/README.md - Integration examples

Troubleshooting

"Docker is not running"

Start Rancher Desktop from your Applications folder. Look for its icon in the menu bar.

"Connection refused"

Wait 10-30 seconds after starting - the server needs time to initialize:

make logs  # Watch until you see "slapd starting"

"Certificate errors"

Verify certificates exist:

ls -la certs/

Regenerate if needed:

make certs-generate --force

"Port already in use"

Check if something is using LDAP ports:

lsof -i :389
lsof -i :636

Still stuck?

Check the full troubleshooting section in README.md or view logs:

make logs

Docker Basics (If You're New)

Since you mentioned being new to Docker, here are the basics:

• Container: A lightweight, isolated environment running your LDAP server
• Image: The blueprint for creating containers (we use osixia/openldap)
• Volume: Persistent storage for LDAP data (survives restarts)
• docker-compose: Tool for managing multi-container applications (LDAP + Admin UI)

When you run make start, Docker:

1. Downloads the LDAP image (first time only)
2. Creates containers from the image
3. Mounts your certificates and data files
4. Starts the LDAP service

The Makefile is just a collection of shortcuts for common Docker commands.

Building Elsewhere

This project works on:

• ✅ MacOS (with Rancher Desktop or Docker Desktop)
• ✅ Linux (with Docker installed)
• ✅ Windows (with Docker Desktop + WSL2)

The same docker-compose.yml works everywhere - that's the beauty of Docker!

To share your setup with a colleague:

# Just copy the whole project
git clone <your-repo>
cd ldap_docker
make dev-setup

Quick Reference Card

Keep these handy:

# Start server
make start

# View logs
make logs

# List users
make test-users

# Stop server
make stop

# Help
make help

Support & Documentation

• Quick commands: make help
• Full guide: README.md
• Examples: examples/README.md
• Command reference: QUICKREF.md

---

Ready to start? Run ./quickstart.sh or make dev-setup and you'll be up in 5 minutes! 🚀

If you run into any issues, check the logs with make logs or see the Troubleshooting section in README.md.