# osixia/container-openldap: Running OpenLDAP as a Docker Image

> The osixia/container-openldap image packages OpenLDAP 2.4.57 into a container that configures itself at startup. It is convenient for test directories and small deployments, but version 1 is deprecated and version 2 lives on the develop branch.

**osixia/container-openldap** — OpenLDAP container image 🐳🪪🌴

- Repository: https://github.com/osixia/container-openldap
- Stars: 4,230 · Forks: 975
- Language: Shell
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/osixia-container-openldap

## What osixia/container-openldap Actually Solves

OpenLDAP ships as a set of daemons and command line tools. Installing it means choosing a suffix, generating a configuration, seeding a database and wiring up TLS. The osixia image removes that setup work by doing it inside the container at first start. The README describes the default behaviour plainly: the image creates an empty LDAP directory for the company Example Inc. and the domain example.org, with the admin password admin. Those defaults are overridable from the docker command line.

The audience is narrow but real. Teams that need a directory service for a test suite, a demo environment or a small internal application get a working LDAP endpoint in one command. Teams that need a hardened production directory with a documented upgrade path are not the target of version 1. The README opens with a deprecation notice: the v1 branch is officially deprecated and will no longer receive updates or fixes, and users are asked to consider migrating to v2 on the develop branch. That notice is the single most important fact about this project.

## How the Image Configures and Boots OpenLDAP

The image is built on the osixia baseimage, which the repository lists under the heading "Under the hood: osixia/light-baseimage". That base handles the startup sequence, and the OpenLDAP layer supplies the slapd configuration. Configuration is not written into slapd.conf; the README states directly that slapd.conf is not used and that changes should go through ldapmodify, ldapadd and ldapdelete.

Two paths hold state. /var/lib/ldap stores the database files, and /etc/ldap/slapd.d stores the configuration. Both are documented as the directories to map as volumes so the data survives outside the container. The README also notes the opposite choice: leaving them unmapped is useful when the image should ship complete with test data, which is the pattern for deriving other images from this one.

Bootstrap is file driven. LDIF files mounted under /container/service/slapd/assets/config/bootstrap/ldif are loaded at startup with either ldapadd or ldapmodify. That gives a repeatable seed step: put the directory entries in a file, mount the directory, and the container loads them on boot. The README's beginner guide also covers using an existing LDAP database, backup, TLS and multi master replication as separate topics, so the image is not limited to the empty-directory case.

## Installing osixia/openldap and Making a First Search

The image is published on Docker Hub as osixia/openldap, and the README pins the current release tag as 1.5.0. The quick start starts a detached container with the default directory. Nothing else is required for a local test.

```bash
docker run --name my-openldap-container --detach osixia/openldap:1.5.0
```

To reach the server from another machine, the README says to publish both port 389 and port 636. Both flags appear together in its example.

```bash
docker run -p 389:389 -p 636:636 --name my-openldap-container --detach osixia/openldap:1.5.0
```

The next step is a search against the default suffix. This runs ldapsearch inside the container against the admin account.

```bash
docker exec my-openldap-container ldapsearch -x -H ldap://localhost -b dc=example,dc=org -D "cn=admin,dc=example,dc=org" -w admin
```

The README shows the expected output as an LDIF block ending with numResponses: 3 and numEntries: 2. If the command fails with ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1), the README says OpenLDAP has not finished starting and to wait before retrying.

To change the defaults, pass environment variables at run time. The README gives this exact combination.

```bash
docker run \
	--env LDAP_ORGANISATION="My Company" \
	--env LDAP_DOMAIN="my-company.com" \
	--env LDAP_ADMIN_PASSWORD="JonSn0w" \
	--detach osixia/openldap:1.5.0
```

On RHEL and CentOS, the README documents a firewall problem when another container on the same host connects to the LDAP server, and gives three firewall-cmd commands to open ports 389 and 636 permanently and reload.

## Data Persistence and the uid Mismatch Trade-off

The volume mapping is where most operational mistakes will happen. The README is explicit that /var/lib/ldap and /etc/ldap/slapd.d should be mapped so the data is saved outside the container. Skip that and the directory lives and dies with the container, which is fine for a test fixture and wrong for anything else.

The image also runs the openldap process under a uid and gid that may not line up with the host. The README calls this out as a source of surprise and offers build arguments, LDAP_OPENLDAP_UID and LDAP_OPENLDAP_GID, to set them explicitly. The example builds an image with gid 1234 and uid 2345 and then verifies with id openldap. This is a build-time decision, not a run-time one, so it belongs in your Dockerfile rather than your compose file.

There is a real tension in the README's advice. It recommends volumes for persistence, then notes that not using volumes is useful when the image should be delivered complete with test data. Both are valid, and the choice depends on whether the directory is a fixture or a service. The documentation does not give guidance on which to pick for a given deployment, so that judgement is left to the reader.

## Deprecation, the v2 Branch and What Version 1 Will Not Get

The limitation that matters most is not technical. Version 1 will not receive updates or fixes. The README states this in its opening section, and points to v2 on the develop branch as the migration target. Anyone planning a long-lived directory on this image is planning on a branch the maintainers have closed.

The release history reflects that split. The 1.5.0 tag dates to 2021-02-19, while a 2.6.10-alpha release appears on 2026-04-27. The stable line and the development line have diverged by both OpenLDAP version and packaging. The README for v1 documents OpenLDAP 2.4.57, so the 2.6 series is a v2 subject, not something this branch will inherit.

The repository itself is not archived, and its last push was on 2026-07-31, so work continues somewhere in the project. But the v1 branch is not where that work lands. The README also links a Known security issues section under Security, which is worth reading before putting this image on a network, though the README excerpt does not enumerate those issues.

This is the wrong tool for a new production directory. It is a reasonable tool for a test harness or a throwaway demo, where the deprecation notice costs little because the container is not meant to outlive the sprint.

## How osixia/openldap Compares with bitnami/openldap

The related searches put bitnami/openldap next to this image, and the difference is in packaging philosophy rather than in the LDAP protocol. Both run slapd in a container and both accept environment variables for the initial suffix and admin credentials. The divergence is in configuration surface and release cadence.

osixia exposes a large environment variable set, documented across Default.yaml and Default.startup.yaml, with several ways to supply them: command line arguments, a linked environment file, Docker Secrets, or a derived image. Bootstrap LDIF files are mounted into a fixed directory path. That is a lot of knobs, and the README's table of contents shows how much of the guide is spent explaining them.

bitnami images generally follow a smaller, more uniform variable scheme across the Bitnami catalogue, which helps if you already run other Bitnami containers and want one mental model. The trade-off is fewer extension points for the OpenLDAP-specific bootstrap behaviour this image provides.

Neither choice resolves the version question. If you need the OpenLDAP 2.6 line, the osixia v1 image is not the path; the project's own answer is the v2 develop branch. Compare candidates on which OpenLDAP version they ship and when they were last released, not on how many variables they expose.

## Licence, Upgrade Cost and Maintenance Reality

The repository is MIT licensed. That is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. It says nothing about the OpenLDAP software inside the image, which carries its own licence from the OpenLDAP project, and nothing about the base image. If you redistribute a derived image, check the licence of each layer rather than assuming MIT covers the whole artifact. This is a description of what the licence file states, not legal advice.

The build tooling is a small Makefile. Targets include build, build-nocache, test, tag-latest, push and release, with NAME set to osixia/openldap and VERSION set to 1.5.0. Tests run through bats against test/test.bats. If you fork the image, that Makefile is the whole build pipeline, and the version string is a single variable to change.

Upgrade cost is the part to weigh honestly. Moving from v1 to v2 is not a tag bump: the README describes v2 as a more flexible and easier-to-customize configuration built on a newer baseimage, which implies configuration files and environment variables will need review. The README does not document a rollback procedure for a v1 to v2 migration, and it does not publish a compatibility matrix. Budget for a staging directory where you replay your bootstrap LDIF and your TLS setup before touching anything that matters.

## Conclusion

Adopt osixia/container-openldap 1.5.0 when you need a disposable OpenLDAP server for integration tests, demos or a small internal directory and you accept that the v1 branch is deprecated. Do not adopt it for a new production directory: the maintainers point users to the v2 develop branch, and the last push to the repository was on 2026-07-31. Before committing, check whether the 2.6.10-alpha release on the develop branch covers the configuration you need, and confirm that the volumes you map for /var/lib/ldap and /etc/ldap/slapd.d are backed up, because the image itself holds no data.

## FAQ

### Is osixia/container-openldap deprecated?

Version 1 is. The README states that the v1 branch is officially deprecated and will no longer receive updates or fixes, and directs users to v2 on the develop branch. The repository itself is not archived and its last push was on 2026-07-31.

### What is the difference between LDAP and OpenLDAP in this image?

LDAP is the protocol; OpenLDAP is the implementation the image runs. The README describes osixia/openldap as a docker image to run OpenLDAP and links to the OpenLDAP project site, and the v1 image documents OpenLDAP 2.4.57.

### What are the limitations of OpenLDAP as packaged in osixia/container-openldap?

The README does not enumerate OpenLDAP's protocol-level limits, but it does state that the v1 branch receives no further updates or fixes and that configuration changes must go through ldapmodify, ldapadd or ldapdelete because slapd.conf is not used. Data also depends on mapping /var/lib/ldap and /etc/ldap/slapd.d as volumes.

## Sources

- [Issues](https://github.com/osixia/container-openldap/issues)
- [License: MIT](https://github.com/osixia/container-openldap/blob/main/LICENSE)
- [osixia/container-openldap on GitHub](https://github.com/osixia/container-openldap)
- [README](https://github.com/osixia/container-openldap/blob/main/README.md)
- [Releases](https://github.com/osixia/container-openldap/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/osixia-container-openldap