Run OpenLDAP with Docker

Run OpenLDAP with Docker, persist directory data and configuration, initialize entries, expose ports safely, configure TLS, and verify the service.

Type
Tutorial
Level
Intermediate
Technologies
OpenLDAP, LDAP, LDAPS
On this page

Introduction: Why OpenLDAP in Docker?

Running OpenLDAP in Docker offers a reproducible, portable way to deploy directory services for development, testing, continuous integration, and small production scenarios. For developers integrating LDAP authentication, setting up short-lived test environments, or experimenting with directory-backed identity models, a containerized OpenLDAP server reduces friction. Compared to traditional bare-metal or VM installs, Docker simplifies setup, teardown, and resetting of directory state—at the cost of requiring explicit volume and configuration management to avoid destructive data loss. However, Docker is not a panacea: persistence, networking, and configuration must be handled directly to ensure reliability, especially as default behaviors often discard state between runs if not handled explicitly.

Selecting a Trusted Docker Image

The de facto standard for running OpenLDAP in containers is the osixia/openldap image. Its documentation covers persistent storage, configuration via environment variables, TLS, LDIF import, and troubleshooting. Notably, the v1 image is deprecated—users should deploy v2 for security fixes and continued maintenance. The Bitnami image, once a mainstay, now requires a commercial license and is less accessible for most open-source development. For general developer workflows, osixia/openldap v2 is the recommended foundation, with widespread community support and clear upgrade guidance for migration from previous versions.

Quickstart: Running OpenLDAP with Docker

Launching OpenLDAP in Docker typically involves starting a container from the osixia/openldap image, exposing standard LDAP ports (389 for plain LDAP, 636 for LDAPS), and setting essential environment variables. These include organizational details and admin credentials. For example, you might run a container exposing ports 389 and 636; however, unless Docker volumes are mounted for data, the entire directory—including configuration and entries—will be lost if the container is removed or recreated.

Persistent Data with Docker Volumes

Persistence is not automatic in Docker. By default, OpenLDAP stores its critical data in two locations: /var/lib/ldap (its database) and /etc/ldap/slapd.d (its runtime configuration). To retain data across container restarts or upgrades, these must be mapped to Docker volumes or host directories. If these paths are not mounted, any change—such as a container update, recreation, or manual removal—will wipe out both data and configuration irretrievably. Persistent data mounting is essential for any workflow intending to preserve directory contents.

Configuration via Environment Variables

The osixia/openldap image exposes a set of environment variables to define OpenLDAP’s initial state. The most crucial are:

  • LDAP_ORGANISATION: Sets the organization name.
  • LDAP_DOMAIN: Sets the base DN for the LDAP directory.
  • LDAP_ADMIN_PASSWORD: Sets the initial password for the LDAP admin account (cn=admin).

These variables control how the directory is bootstrapped during first initialization. Changing them after the first boot will not retroactively reconfigure an existing persisted directory; a fresh directory is required for changes to take effect.

Initial LDIF Import and Schema Extension

Seeding OpenLDAP with custom data or schema extensions at startup is supported, but only if LDIF files are mounted in the correct directory within the container. For osixia/openldap, LDIF files placed in /container/service/slapd/assets/config/bootstrap/ldif/custom/ will be auto-imported when the container initializes a new directory. If you omit this mount or use a different location, the LDIF will not be loaded. This is a common pitfall. The same approach applies to custom schema files and directory bootstrap: file locations are tightly controlled, and imports occur only when the database is first created.

Securing OpenLDAP in Docker

OpenLDAP containers support LDAPS (LDAP over SSL/TLS). By default, osixia/openldap auto-generates self-signed certificates, which may not be trusted by clients beyond initial testing. For production or secure environments, you must mount your own CA-signed certificates into /container/service/slapd/assets/certs. Relying on autogenerated or self-signed certificates in production is risky: external services may refuse connections, and data could be exposed in cleartext. Always verify certificate trust and replace defaults before exposing LDAP to untrusted networks.

Adding WebUI: phpLDAPadmin Integration

Browser-based management is possible by deploying a companion phpLDAPadmin container, such as osixia/docker-phpLDAPadmin. phpLDAPadmin is not a server—it's a web UI that connects to an external OpenLDAP instance. The connection between phpLDAPadmin and OpenLDAP is typically defined with the PHPLDAPADMIN_LDAP_HOSTS environment variable, pointing to your directory container. Both containers should be on the same Docker network. Expose the phpLDAPadmin web interface on a separate port, such as 6443, for access. The WebUI lets you browse, add, and modify entries graphically, but all changes are made via the LDAP protocol to the actual server instance.

Common Troubleshooting Scenarios

Most operational issues fall into a few categories:

  • Lost Data: If /var/lib/ldap and /etc/ldap/slapd.d are not mounted to persistent Docker volumes, your directory will be wiped whenever the container is removed.
  • Permission Errors: Containerized OpenLDAP can encounter file permission problems if the mounted volumes or files are not owned or accessible by the container’s internal user. Pass the --copy-service argument or adjust ownership on host volumes as needed.
  • LDIF Not Imported: LDIF files for bootstrap or schema extension must be present in /container/service/slapd/assets/config/bootstrap/ldif/custom/ on first container initialization. Wrong paths or late mounts mean no import will occur.
  • Startup Failures: Often linked to incorrect file permissions, missing environment variables, or residual corrupted state from incomplete previous runs.

Effective diagnosis begins by inspecting openldap container logs and confirming mount points, file ownership, and directory state before troubleshooting at the application or code level.

Best Practices, Gotchas, and Maintaining Deployments

To avoid destructive mistakes:

  • Always mount persistent volumes for both /var/lib/ldap and /etc/ldap/slapd.d.
  • Never rely on default credentials or self-signed certificates in production.
  • Record the exact image version (e.g., osixia/openldap:v2) you deploy; avoid mixing versions across updates as schema or state incompatibility can result.
  • Understand that changes to initialization variables require a fresh directory and full data reimport to take effect.
  • Practice rolling backups of your host-mounted volumes before upgrades or container replacement.

Comparing Dockerized vs Standard OpenLDAP Deployments

Dockerized OpenLDAP trades operational complexity for fast, reproducible setup—ideal for development, testing, and lightweight production. Data and configuration persistence are externalized and explicit, not the default. Integration with automation and reproducibility (via docker-compose or similar tools) is straightforward and scriptable. However, unlike standard installations, the container is ephemeral by default: if persistent storage is overlooked, critical data is easily lost. Security defaults (credentials, TLS) are often not suitable for real-world deployment unless explicitly hardened. Migration, high-availability, and advanced scale-out remain more nuanced in a containerized model and may require further orchestration compared to monolith or systemd-managed installations.

Sources:

  • https://github.com/osixia/container-openldap
  • https://github.com/osixia/docker-phpLDAPadmin
  • https://docs.mirantis.com/mke4/4.1.0/tutorials/authentication-provider-setup/setting-up-openldap-as-an-ldap-provider/
  • https://docs.keeper.io/keeper-connection-manager/authentication/authenticating-users-with-ldap/storing-connection-data-within-ldap

Sources

Related resources