# Installing LLDAP - [With Docker](#with-docker) - [With Podman](#with-podman) - [With Kubernetes](#with-kubernetes) - [TrueNAS SCALE](#truenas-scale) - [From a package repository](#from-a-package-repository) - [With FreeBSD](#with-freebsd) - [From source](#from-source) - [Backend](#backend) - [Frontend](#frontend) - [Cross-compilation](#cross-compilation) ### With Docker The image is available at `lldap/lldap`. You should persist the `/data` folder, which contains your configuration and the SQLite database (you can remove this step if you use a different DB and configure with environment variables only). Configure the server by copying the `lldap_config.docker_template.toml` to `/data/lldap_config.toml` and updating the configuration values (especially the `jwt_secret` and `ldap_user_pass`, unless you override them with env variables). Environment variables should be prefixed with `LLDAP_` to override the configuration. If the `lldap_config.toml` doesn't exist when starting up, LLDAP will use default one. The default admin password is `password`, you can change the password later using the web interface. Secrets can also be set through a file. The filename should be specified by the variables `LLDAP_JWT_SECRET_FILE` or `LLDAP_KEY_SEED_FILE`, and the file contents are loaded into the respective configuration parameters. Note that `_FILE` variables take precedence. Example for docker compose: - You can use either the `:latest` tag image or `:stable` as used in this example. - `:latest` tag image contains recently pushed code or feature tests, in which some instability can be expected. - If `UID` and `GID` no defined LLDAP will use default `UID` and `GID` number `1000`. - If no `TZ` is set, default `UTC` timezone will be used. - You can generate the secrets by running `./generate_secrets.sh` ```yaml version: "3" volumes: lldap_data: driver: local services: lldap: image: lldap/lldap:stable ports: # For LDAP, not recommended to expose, see Usage section. #- "3890:3890" # For LDAPS (LDAP Over SSL), enable port if LLDAP_LDAPS_OPTIONS__ENABLED set true, look env below #- "6360:6360" # For the web front-end - "17170:17170" volumes: - "lldap_data:/data" # Alternatively, you can mount a local folder # - "./lldap_data:/data" environment: - UID=#### - GID=#### - TZ=####/#### - LLDAP_JWT_SECRET=REPLACE_WITH_RANDOM - LLDAP_KEY_SEED=REPLACE_WITH_RANDOM - LLDAP_LDAP_BASE_DN=dc=example,dc=com - LLDAP_LDAP_USER_PASS=CHANGE_ME # If the password contains '$', escape it (e.g. Pas$$word sets Pas$word) # If using LDAPS, set enabled true and configure cert and key path # - LLDAP_LDAPS_OPTIONS__ENABLED=true # - LLDAP_LDAPS_OPTIONS__CERT_FILE=/path/to/certfile.crt # - LLDAP_LDAPS_OPTIONS__KEY_FILE=/path/to/keyfile.key # You can also set a different database: # - LLDAP_DATABASE_URL=mysql://mysql-user:password@mysql-server/my-database # - LLDAP_DATABASE_URL=postgres://postgres-user:password@postgres-server/my-database # If using SMTP, set the following variables # - LLDAP_SMTP_OPTIONS__ENABLE_PASSWORD_RESET=true # - LLDAP_SMTP_OPTIONS__SERVER=smtp.example.com # - LLDAP_SMTP_OPTIONS__PORT=465 # Check your smtp provider's documentation for this setting # - LLDAP_SMTP_OPTIONS__SMTP_ENCRYPTION=TLS # How the connection is encrypted, either "NONE" (no encryption, port 25), "TLS" (sometimes called SSL, port 465) or "STARTTLS" (sometimes called TLS, port 587). # - LLDAP_SMTP_OPTIONS__USER=no-reply@example.com # The SMTP user, usually your email address # - LLDAP_SMTP_OPTIONS__PASSWORD=PasswordGoesHere # The SMTP password # - LLDAP_SMTP_OPTIONS__FROM=no-reply # The header field, optional: how the sender appears in the email. The first is a free-form name, followed by an email between <>. # - LLDAP_SMTP_OPTIONS__TO=admin # Same for reply-to, optional. ``` Then the service will listen on two ports, one for LDAP and one for the web front-end. ### With Podman LLDAP works well with rootless Podman either through command line deployment or using [quadlets](../example_configs/podman-quadlets/). The example quadlets include configuration with postgresql and file based secrets, but have comments for several other deployment strategies. ### With Kubernetes See https://github.com/Evantage-WS/lldap-kubernetes for a LLDAP deployment for Kubernetes You can bootstrap your lldap instance (users, groups) using [bootstrap.sh](../example_configs/bootstrap/bootstrap.md#kubernetes-job). It can be run by Argo CD for managing users in git-opt way, or as a one-shot job. ### TrueNAS SCALE LLDAP can be installed on **TrueNAS SCALE** using the built-in Apps catalog, allowing users to deploy and manage LLDAP directly from the TrueNAS web interface without manually maintaining containers. To install: 1. Open the TrueNAS web interface. 2. Navigate to **Apps → Discover Apps**. 3. Search for **LLDAP** and click **Install**. 4. Provide the required configuration values such as: - Base DN - Admin credentials - LDAP / LDAPS ports - Persistent storage dataset TrueNAS supports selecting certificates for LDAPS and configuring a public web URL. When LDAPS is enabled, it is recommended to disable the unencrypted LDAP port to ensure secure communication. A full, step-by-step TrueNAS-specific guide (including recommended ports, certificate configuration, and common integrations) is available here: 👉 [example_configs/truenas-install.md](https://github.com/lldap/lldap/blob/main/example_configs/truenas-install.md) ### From a package repository **Do not open issues in this repository for problems with third-party pre-built packages. Report issues downstream.** Depending on the distribution you use, it might be possible to install LLDAP from a package repository, officially supported by the distribution or community contributed. Each package offers a [systemd service](https://wiki.archlinux.org/title/systemd#Using_units) `lldap.service` or [rc.d_lldap](../example_configs/freebsd/rc.d_lldap) `rc.d/lldap` to (auto-)start and stop lldap.
When using the distributed packages, the default login is `admin/password`. You can change that from the web UI after starting the service.
Arch Linux
Arch Linux offers unofficial support through the Arch User Repository (AUR).
The package descriptions can be used to create and install packages.

Support: Discussions
Package repository: Arch User Repository

Package name Maintainer Description
lldap @Zepmann Builds the latest stable version.
lldap-bin @Zepmann Uses the latest pre-compiled binaries from the releases in this repository.
This package is recommended if you want to run LLDAP on a system with limited resources.
lldap-git Builds the latest main branch code.
LLDAP configuration file: /etc/lldap.toml
Debian
Unofficial Debian support is offered through the openSUSE Build Service.

Maintainer: @Masgalor
Support: Codeberg, Discussions
Package repository: SUSE openBuildService
Available packages: lldap Light LDAP server for authentication.
lldap-extras Meta-Package for LLDAP and its tools and extensions.
lldap-migration-tool CLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-password CLI tool to set a user password in LLDAP.
lldap-cli LLDAP-CLI is an unofficial command line interface for LLDAP.
LLDAP configuration file: /etc/lldap/lldap_config.toml
CentOS
Unofficial CentOS support is offered through the openSUSE Build Service.

Maintainer: @Masgalor
Support: Codeberg, Discussions
Package repository: SUSE openBuildService
Available packages: lldap Light LDAP server for authentication.
lldap-extras Meta-Package for LLDAP and its tools and extensions.
lldap-migration-tool CLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-password CLI tool to set a user password in LLDAP.
lldap-cli LLDAP-CLI is an unofficial command line interface for LLDAP.
LLDAP configuration file: /etc/lldap/lldap_config.toml
Fedora
Unofficial Fedora support is offered through the openSUSE Build Service.

Maintainer: @Masgalor
Support: Codeberg, Discussions
Package repository: SUSE openBuildService
Available packages: lldap Light LDAP server for authentication.
lldap-extras Meta-Package for LLDAP and its tools and extensions.
lldap-migration-tool CLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-password CLI tool to set a user password in LLDAP.
lldap-cli LLDAP-CLI is an unofficial command line interface for LLDAP.
LLDAP configuration file: /etc/lldap/lldap_config.toml
OpenSUSE
Unofficial OpenSUSE support is offered through the openSUSE Build Service.

Maintainer: @Masgalor
Support: Codeberg, Discussions
Package repository: SUSE openBuildService
Available packages: lldap Light LDAP server for authentication.
lldap-extras Meta-Package for LLDAP and its tools and extensions.
lldap-migration-tool CLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-password CLI tool to set a user password in LLDAP.
lldap-cli LLDAP-CLI is an unofficial command line interface for LLDAP.
LLDAP configuration file: /etc/lldap/lldap_config.toml
Ubuntu
Unofficial Ubuntu support is offered through the openSUSE Build Service.

Maintainer: @Masgalor
Support: Codeberg, Discussions
Package repository: SUSE openBuildService
Available packages: lldap Light LDAP server for authentication.
lldap-extras Meta-Package for LLDAP and its tools and extensions.
lldap-migration-tool CLI migration tool to go from OpenLDAP to LLDAP.
lldap-set-password CLI tool to set a user password in LLDAP.
lldap-cli LLDAP-CLI is an unofficial command line interface for LLDAP.
LLDAP configuration file: /etc/lldap/lldap_config.toml
FreeBSD
Official FreeBSD support is offered through the FreeBSD Freshport Build Service.

Maintainer: @aokblast
Support: Bugzilla, Discussions
Package repository: FreeBSD Freshport Build
FreeBSD Setup and Migration Manual: Using FreeBSD
Available packages: lldap Light LDAP server for authentication.
LLDAP configuration file: /usr/local/lldap_server/lldap_config.toml
### From source #### Backend To compile the project, you'll need: - curl and gzip: `sudo apt install curl gzip` - Rust/Cargo: [rustup.rs](https://rustup.rs/) Then you can compile the server (and the migration tool if you want): ```shell cargo build --release -p lldap -p lldap_migration_tool ``` The resulting binaries will be in `./target/release/`. Alternatively, you can just run `cargo run -- run` to run the server. #### Frontend To bring up the server, you'll need to compile the frontend. In addition to `cargo`, you'll need WASM-pack, which can be installed by running `cargo install wasm-pack`. Then you can build the frontend files with ```shell ./app/build.sh ``` (you'll need to run this after every front-end change to update the WASM package served). The default config is in `src/infra/configuration.rs`, but you can override it by creating an `lldap_config.toml`, setting environment variables or passing arguments to `cargo run`. Have a look at the docker template: `lldap_config.docker_template.toml`. You can also install it as a systemd service, see [lldap.service](../example_configs/lldap.service). ### Cross-compilation Docker images are provided for AMD64, ARM64 and ARM/V7. If you want to cross-compile yourself, you can do so by installing [`cross`](https://github.com/rust-embedded/cross): ```sh cargo install cross cross build --target=armv7-unknown-linux-musleabihf -p lldap --release ./app/build.sh ``` (Replace `armv7-unknown-linux-musleabihf` with the correct Rust target for your device.) You can then get the compiled server binary in `target/armv7-unknown-linux-musleabihf/release/lldap` and the various needed files (`index.html`, `main.js`, `pkg` folder) in the `app` folder. Copy them to the Raspberry Pi (or other target), with the folder structure maintained (`app` files in an `app` folder next to the binary).