What LLDAP does
LLDAP is a free directory server written in Rust. It stores users and groups in an SQLite database, presents them to applications over the LDAP protocol, and gives administrators a web interface to manage them. It does not try to do everything: no schema to write, no replication, no fine-grained ACLs. It does what Authelia, Gitea, Nextcloud, Keycloak or Jellyfin need — check a password, list the members of a group — and nothing more.
What LLDAP gives you
- One account per person — the same username and password in all your applications.
- Offboarding in one click — disable the account in LLDAP and access closes everywhere.
- Groups that grant access — one group per application, and each application only lets its members in.
- A web interface — create, edit and organise accounts without ever writing an LDIF file.
- Self-service reset — each user changes their password by email.
- A tiny footprint — a few megabytes of memory, next to the applications it serves.
Local accounts, OpenLDAP or LLDAP
Scroll the table
| Local accounts per application | OpenLDAP | LLDAP | |
|---|---|---|---|
| Accounts to manage | One per application | One per person | One per person |
| Administration | In each application | LDIF files and command line | Web interface |
| Getting started | None | Schemas and ACLs to write | One container and four variables |
| Memory at rest | — | A few tens of MB | A few MB |
| When someone leaves | Account to close everywhere | A single account | A single account |
Prepare the server
An Ubuntu 24.04 VPS with 1 GB of RAM is plenty: LLDAP uses a few megabytes, and it will usually share the machine with the applications it serves. Install Docker and the Compose plugin, and plan a subdomain such as ldap.example.com pointing to the VPS: the administration interface must be served over HTTPS, since passwords go through it. The LDAP port itself will never be published on the Internet.
Install LLDAP with Docker Compose
Prepare the folder and the .env file
Three secrets: the password of the
adminaccount, the key that signs interface sessions and the seed of the server's private key.mkdir -p /opt/lldap && cd /opt/lldap cat > .env <<EOF ADMIN_PASSWORD=$(openssl rand -hex 16) JWT_SECRET=$(openssl rand -hex 32) KEY_SEED=$(openssl rand -hex 32) EOF chmod 600 .envWrite the docker-compose.yml file
A single service. Both ports are only published on the loopback: the web interface (17170) will go through nginx, and the LDAP port (3890) stays reserved for the VPS. Replace
dc=example,dc=comwith the base of your choice, for exampledc=yourcompany,dc=com.services: lldap: image: lldap/lldap:v0.6.3-alpine restart: unless-stopped ports: - "127.0.0.1:17170:17170" - "127.0.0.1:3890:3890" environment: TZ: UTC LLDAP_LDAP_BASE_DN: "dc=example,dc=com" LLDAP_LDAP_USER_PASS: ${ADMIN_PASSWORD} LLDAP_JWT_SECRET: ${JWT_SECRET} LLDAP_KEY_SEED: ${KEY_SEED} LLDAP_HTTP_URL: "https://ldap.example.com" volumes: - lldap-data:/data networks: - lldap networks: lldap: name: lldap volumes: lldap-data: {}Start and check
On first start, LLDAP creates its system groups and the
adminaccount with the password from the.envfile. It answers within seconds.docker compose up -d docker compose logs lldap | grep -i admin curl -sI http://127.0.0.1:17170/ | head -n 1Test the directory over LDAP
The
lldapDocker network lets a container reach the directory by name.ldapwhoamimust answer with the DN of the admin account.docker run --rm --network lldap alpine:3.20 sh -c \ "apk add -q openldap-clients && ldapwhoami -x -H ldap://lldap:3890 \ -D uid=admin,ou=people,dc=example,dc=com -W"
Change the admin password and keep the LDAP port private
The LLDAP_LDAP_USER_PASS password is only used on first start: change it afterwards in the interface and it will no longer be overwritten. And never publish port 3890 on 0.0.0.0: LDAP without TLS carries passwords in clear text, and your applications have no need to reach it from the Internet.
Publish the interface over HTTPS behind nginx
Get a certificate with certbot (certbot certonly --nginx -d ldap.example.com), then declare a server block that forwards to local port 17170. Remember to put the same address in LLDAP_HTTP_URL: password reset links use it.
server {
listen 443 ssl;
server_name ldap.example.com;
ssl_certificate /etc/letsencrypt/live/ldap.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/ldap.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:17170;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto https;
}
}Connect your applications to the directory
First create, for each application, a service account (for example svc-gitea) and put it in the lldap_strict_readonly group: it can read the directory without changing anything. Then attach the application's container to the lldap network and enter the directory in its authentication settings:
docker network connect lldap gitea
# Server URL : ldap://lldap:3890
# Bind DN : uid=svc-gitea,ou=people,dc=example,dc=com
# User base : ou=people,dc=example,dc=com
# Filter : (&(objectClass=person)(uid=%s))The same pattern works for Nextcloud (the LDAP user and group backend app), Authelia (authentication_backend.ldap with the lldap implementation) or Keycloak (LDAP user federation). To let only some users in, add a memberOf condition on the application's group to the filter.
Enable password reset by email
Without an SMTP server, only the administrator can change a forgotten password. Add the following variables to the lldap service, with a sending account from your mail provider, then run docker compose up -d again: the “Forgot password” link appears on the login screen, and the email it sends points to the address in LLDAP_HTTP_URL.
environment:
LLDAP_SMTP_OPTIONS__ENABLE_PASSWORD_RESET: "true"
LLDAP_SMTP_OPTIONS__SERVER: smtp.example.com
LLDAP_SMTP_OPTIONS__PORT: "587"
LLDAP_SMTP_OPTIONS__SMTP_ENCRYPTION: STARTTLS
LLDAP_SMTP_OPTIONS__USER: [email protected]
LLDAP_SMTP_OPTIONS__PASSWORD: ${SMTP_PASSWORD}
LLDAP_SMTP_OPTIONS__FROM: "LLDAP <[email protected]>"Test with an ordinary account before announcing the feature to the team: a link pointing to localhost means the public address was not declared correctly.
Example: Authelia backed by LLDAP
Authelia knows LLDAP and offers a dedicated implementation that sets the filters and attributes for you. The svc-authelia service account must belong to the lldap_password_manager group if you want users to change their password from Authelia; otherwise lldap_strict_readonly is enough.
authentication_backend:
ldap:
implementation: lldap
address: ldap://lldap:3890
base_dn: dc=example,dc=com
user: uid=svc-authelia,ou=people,dc=example,dc=com
password: '<service-account-password>'Finally attach the Authelia container to the lldap network, restart it and sign in with an account created in LLDAP: the same identity now opens every application protected by Authelia.
Backup and updates
LLDAP's whole state lives in the lldap-data volume: the SQLite database, the configuration and the server's private key. An archive of the volume, with LLDAP stopped for a few seconds, is enough to restore everything.
cd /opt/lldap
docker compose stop lldap
docker run --rm -v lldap_lldap-data:/data -v "$PWD":/backup alpine:3.20 \
tar czf /backup/lldap-$(date +%F).tar.gz -C /data .
docker compose start lldapTo update, change the image tag in docker-compose.yml, read the release notes, then run docker compose pull && docker compose up -d: LLDAP migrates its database on start.
LLDAP in one click on ServOrbit
The ServOrbit Marketplace installs exactly this stack: the official lldap/lldap image, secrets drawn at install time, an admin account created with a generated password, the web interface published over HTTPS on a subdomain of your domain or on the VPS's free subdomain, and the LDAP port kept on the loopback. The password is shown in your client area; all that is left is to create your users and connect your applications.
servorbit.com/ma-en/blog/self-host-lldap-vps-ldap-directory
