Self-hosting

LLDAP on a VPS: a lightweight LDAP directory for your apps

Every self-hosted application arrives with its own user list: a Gitea account, a Nextcloud account, a Grafana account, and as many passwords to revoke the day someone leaves the team. An LDAP directory has solved this for twenty years, but OpenLDAP puts most small teams off. LLDAP keeps the essentials in a single lightweight container. This guide installs it on a VPS with Docker Compose, publishes its interface over HTTPS behind nginx, keeps the LDAP port private and connects your applications to it.

Deploy on a VPS Cloud →
7 min read4 steps

Orbi AI agentThe contents follow the article; related articles wait at the bottom.

Contents· What LLDAP does1/12
  1. 01What LLDAP does
  2. 02What LLDAP gives you
  3. 03Local accounts, OpenLDAP or LLDAP
  4. 04Prepare the server
  5. 05Install LLDAP with Docker Compose
  6. 06Change the admin password and keep the LDAP port private
  7. 07Publish the interface over HTTPS behind nginx
  8. 08Connect your applications to the directory
  9. 09Enable password reset by email
  10. 10Example: Authelia backed by LLDAP
  11. 11Backup and updates
  12. 12LLDAP in one click on ServOrbit

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 applicationOpenLDAPLLDAP
Accounts to manageOne per applicationOne per personOne per person
AdministrationIn each applicationLDIF files and command lineWeb interface
Getting startedNoneSchemas and ACLs to writeOne container and four variables
Memory at rest—A few tens of MBA few MB
When someone leavesAccount to close everywhereA single accountA 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

  1. Prepare the folder and the .env file

    Three secrets: the password of the admin account, 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 .env
  2. Write 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=com with the base of your choice, for example dc=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: {}
  3. Start and check

    On first start, LLDAP creates its system groups and the admin account with the password from the .env file. 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 1
  4. Test the directory over LDAP

    The lldap Docker network lets a container reach the directory by name. ldapwhoami must 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 lldap

To 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.

Share this articleservorbit.com/ma-en/blog/self-host-lldap-vps-ldap-directory

One directory for all your applications

Prices shown excluding VAT, with their renewal price.