Skip to content
Klutch.sh Docs

Deploying a LightLDAP App

Introduction

LightLDAP is a lightweight LDAP directory service suitable for development and small production deployments. Deploying LightLDAP with a Dockerfile on Klutch.sh gives you 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 LDAP queries, and production tips.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your LightLDAP configuration (GitHub is the only supported git source)
  • Docker familiarity and basic LDAP administration knowledge
  • Storage for LDAP database and configuration

For platform onboarding, see the Quick Start.

Architecture and ports

  • LDAP listens on TCP 389 (and 636 for LDAPS). Set the internal container port to 389 for standard LDAP. Use TCP traffic in Klutch.sh.
  • If you enable LDAPS, expose 636 internally via a separate app or configure TLS in the same container.
  • Persistent storage is required for LDAP database (/var/lib/ldap) and configuration (/etc/ldap/slapd.d).

Repository layout

lightldap/
├── Dockerfile              # Must be at repo root for auto-detection
├── config/                 # Optional custom config/LDIFs
├── ldif/                   # Seed data (optional)
└── README.md

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

Installation (local) and starter commands

Test locally with the official OpenLDAP-based image:

Terminal window
docker run --rm -p 389:389 \
  -e LDAP_ORGANISATION="Example Org" \
  -e LDAP_DOMAIN="example.com" \
  -e LDAP_ADMIN_PASSWORD="change_me" \
  -v $(pwd)/data/ldap:/var/lib/ldap \
  -v $(pwd)/data/slapd:/etc/ldap/slapd.d \
  osixia/openldap:1.5.0

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec /container/tool/run

Make it executable with chmod +x start.sh.

Dockerfile for LightLDAP (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


WORKDIR /app


# Optional: copy custom configuration or seed LDIF files
COPY config /container/service/slapd/assets/config
COPY ldif /container/service/slapd/assets/config/bootstrap/ldif/custom


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

Notes:

  • Pin the image tag for reproducible behavior.
  • Add TLS certs via volume mounts and update slapd configuration if you enable LDAPS.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=389
  • LDAP_ORGANISATION="Example Org"
  • LDAP_DOMAIN=example.com
  • LDAP_ADMIN_PASSWORD=<strong-password>
  • LDAP_TLS=false (set true if you configure TLS and provide certs)
  • LDAP_READONLY_USER=false (set true and add credentials if needed)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo LightLDAP uses prebuilt image"
  • NIXPACKS_START_CMD=/container/tool/run
  • NIXPACKS_JDK_VERSION=17 (not typically needed but provided for completeness)

Attach persistent volumes

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

  • /var/lib/ldap — required for LDAP database files.
  • /etc/ldap/slapd.d — required for configuration.
  • /container/service/slapd/assets/certs — optional if you mount TLS certificates.

Ensure these paths are writable inside the container.

Deploy LightLDAP 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.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose TCP traffic for LightLDAP.
  3. Set the internal port to 389.
  4. Add the environment variables above (organisation, domain, admin password, TLS flags, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /var/lib/ldap and /etc/ldap/slapd.d (plus certs if used), selecting sizes that fit your directory data.
  6. Deploy. Your LDAP endpoint will be reachable at example-app.klutch.sh:8000 over TCP for clients.

Sample LDAP query

Search the directory (replace host and credentials):

Terminal window
ldapsearch -H ldap://example-app.klutch.sh:8000 -x -D "cn=admin,dc=example,dc=com" -w "<admin-password>" -b "dc=example,dc=com" "(objectClass=person)"

Health checks and production tips

  • Use ldapsearch for simple health checks or bind tests.
  • Enforce TLS/LDAPS for production; mount certs and set LDAP_TLS=true.
  • Rotate admin and read-only user passwords regularly; keep them only in Klutch.sh secrets.
  • Monitor disk usage on /var/lib/ldap and resize volumes before they fill.
  • Keep image tags pinned; upgrade intentionally after testing.

LightLDAP on Klutch.sh combines reproducible Docker builds with managed secrets, persistent volumes for directory data, and flexible TCP routing. With the Dockerfile at the repo root and port 389 configured (8000 externally for clients), you can serve LDAP directories without extra YAML or workflow overhead.