Skip to content
Klutch.sh Docs

Deploying an OpenLDAP App

Introduction

OpenLDAP is an open-source implementation of the Lightweight Directory Access Protocol (LDAP) for centralized authentication and directory services. Deploying OpenLDAP with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for directory data—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your OpenLDAP Dockerfile (GitHub is the only supported git source)
  • Base DN and admin credentials for your directory
  • Optional TLS certificates for LDAPS

For onboarding, see the Quick Start.

Architecture and ports

  • OpenLDAP listens on internal port 389 (TCP). Choose TCP traffic and set the internal port to 389.
  • If you enable LDAPS, also consider exposing 636 via a second app/port.
  • Persistent storage is required for directory data and configuration.

Repository layout

openldap/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets (admin passwords, TLS keys) out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t openldap-local .
docker run -p 389:389 \
  -e LDAP_DOMAIN=example.com \
  -e LDAP_ADMIN_PASSWORD=changeme \
  openldap-local

Dockerfile for OpenLDAP (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM osixia/openldap:1.5.0


ENV LDAP_ORGANISATION="Example Corp" \
    LDAP_DOMAIN="example.com" \
    LDAP_ADMIN_PASSWORD="changeme" \
    LDAP_CONFIG_PASSWORD="changeme"


EXPOSE 389 636
CMD ["/container/tool/run"]

Notes:

  • Pin the image tag (e.g., 1.5.0) for stability and upgrade intentionally.
  • Use strong passwords and move them to Klutch.sh secrets.
  • Enable TLS by mounting certs into /container/service/slapd/assets/certs and setting LDAP_TLS* variables.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • LDAP_ORGANISATION=<Your Org>
  • LDAP_DOMAIN=<your-domain.com>
  • LDAP_ADMIN_PASSWORD=<strong-password>
  • LDAP_CONFIG_PASSWORD=<strong-password>
  • Optional TLS: LDAP_TLS=true, LDAP_TLS_CRT_FILENAME=<crt>, LDAP_TLS_KEY_FILENAME=<key>, LDAP_TLS_CA_CRT_FILENAME=<ca>, and mount certs.

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=/container/tool/run

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/lib/ldap — directory data.
  • /etc/ldap/slapd.d — directory configuration.
  • /container/service/slapd/assets/certs — certificates (if using TLS).

Ensure these paths are writable inside the container.

Deploy OpenLDAP on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select TCP traffic and set the internal port to 389 (and 636 if you expose LDAPS via another app/port).
  4. Add the environment variables above, including TLS settings if enabled.
  5. Attach persistent volumes for /var/lib/ldap, /etc/ldap/slapd.d, and optionally certs, sizing them for your directory.
  6. Deploy. Connect to example-app.klutch.sh:8000 (mapped to internal 389) with your LDAP clients.

Sample usage

Test a bind with ldapwhoami (from a client):

Terminal window
ldapwhoami -x -H ldap://example-app.klutch.sh:8000 -D "cn=admin,dc=example,dc=com" -w "<admin_password>"

Add an entry via LDIF:

Terminal window
cat <<'EOF' > user.ldif
dn: uid=jdoe,dc=example,dc=com
objectClass: inetOrgPerson
sn: Doe
cn: John Doe
uid: jdoe
mail: jdoe@example.com
EOF


ldapadd -x -H ldap://example-app.klutch.sh:8000 -D "cn=admin,dc=example,dc=com" -w "<admin_password>" -f user.ldif

Health checks and production tips

  • Add a TCP probe on port 389 (or 636 for LDAPS).
  • Enforce TLS for credentials; keep certs in volumes and rotate them regularly.
  • Store admin passwords only in Klutch.sh secrets and rotate them.
  • Monitor disk usage on /var/lib/ldap; resize before it fills.
  • Pin image versions and test upgrades in staging; back up data before updates.

OpenLDAP on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 389 configured, and directory data persisted, you can run secure directory services without extra YAML or workflow overhead.