From c658666b3f67a75d5387f91bb90aedce3b24a675 Mon Sep 17 00:00:00 2001 From: Alexandre Foley Date: Mon, 30 Jun 2025 13:47:32 -0400 Subject: [PATCH] example_configs: Quadlet documentation and improvements --- .../podman-quadlets/lldap-backend.network | 2 + .../podman-quadlets/lldap-db.container | 2 +- .../podman-quadlets/lldap-db.volume | 4 ++ .../podman-quadlets/lldap-frontend.network | 2 + .../podman-quadlets/lldap.container | 16 +++-- example_configs/podman-quadlets/readme.md | 61 +++++++++++++++++++ 6 files changed, 77 insertions(+), 10 deletions(-) create mode 100644 example_configs/podman-quadlets/lldap-backend.network create mode 100644 example_configs/podman-quadlets/lldap-db.volume create mode 100644 example_configs/podman-quadlets/lldap-frontend.network create mode 100644 example_configs/podman-quadlets/readme.md diff --git a/example_configs/podman-quadlets/lldap-backend.network b/example_configs/podman-quadlets/lldap-backend.network new file mode 100644 index 0000000..bb2a6ca --- /dev/null +++ b/example_configs/podman-quadlets/lldap-backend.network @@ -0,0 +1,2 @@ +[Network] +# NetworkDeleteOnStop=true \ No newline at end of file diff --git a/example_configs/podman-quadlets/lldap-db.container b/example_configs/podman-quadlets/lldap-db.container index 1236400..e303609 100644 --- a/example_configs/podman-quadlets/lldap-db.container +++ b/example_configs/podman-quadlets/lldap-db.container @@ -18,7 +18,7 @@ ContainerName=lldap-db Image=docker.io/postgres:17 # this is optional to keep db/web services separate -Network=backend.network +Network=lldap-backend.network # health check HealthCmd=pg_isready -U lldapuser -d lldap diff --git a/example_configs/podman-quadlets/lldap-db.volume b/example_configs/podman-quadlets/lldap-db.volume new file mode 100644 index 0000000..ca44492 --- /dev/null +++ b/example_configs/podman-quadlets/lldap-db.volume @@ -0,0 +1,4 @@ + +[Volume] +VolumeName=lldap-db + diff --git a/example_configs/podman-quadlets/lldap-frontend.network b/example_configs/podman-quadlets/lldap-frontend.network new file mode 100644 index 0000000..bb2a6ca --- /dev/null +++ b/example_configs/podman-quadlets/lldap-frontend.network @@ -0,0 +1,2 @@ +[Network] +# NetworkDeleteOnStop=true \ No newline at end of file diff --git a/example_configs/podman-quadlets/lldap.container b/example_configs/podman-quadlets/lldap.container index bd2e6e9..b3b9f78 100644 --- a/example_configs/podman-quadlets/lldap.container +++ b/example_configs/podman-quadlets/lldap.container @@ -17,8 +17,8 @@ ContainerName=lldap Image=docker.io/lldap/lldap:stable-debian # using multiple networks for traefik and db, not essential -Network=frontend.network -Network=backend.network +Network=lldap-frontend.network +Network=lldap-backend.network # environment variables Environment=UID=1000 @@ -32,10 +32,6 @@ Environment=LLDAP_KEY_SEED_FILE=/run/secrets/lldap-key-seed Environment=LLDAP_JWT_SECRET_FILE=/run/secrets/lldap-jwt-secret Environment=LLDAP_LDAP_USER_PASS_FILE=/run/secrets/lldap-ldap-user-pass -# bootstrap.sh environment variables -# Environment=LLDAP_URL=http://localhost:17170 -# Environment=LLDAP_ADMIN_USERNAME=admin -# Environment=LLDAP_ADMIN_PASSWORD_FILE=/run/secrets/lldap-ldap-user-pass # health check HealthCmd=/app/lldap healthcheck @@ -61,10 +57,12 @@ Secret=lldap-ldap-user-pass,type=mount,uid=1000 # Secret=lldap-key-seed,type=env,target=LLDAP_KEY_SEED # Secret=lldap-ldap-user-pass,type=env,target=LLDAP_LDAP_USER_PASS -# for bootstrap.sh script +# Bootstrapping. Uncomment the remainder of this section. Once +# the bootstrap files are ready. re-comment once bootstrapping is done. # Secret=lldap-ldap-user-pass,type=env,target=LLDAP_ADMIN_PASSWORD - -# volumes - only needed for bootstrap.sh +# Environment=LLDAP_URL=http://localhost:17170 +# Environment=LLDAP_ADMIN_USERNAME=admin +# Environment=LLDAP_ADMIN_PASSWORD_FILE=/run/secrets/lldap-ldap-user-pass # Volume=%h/containers/lldap:/bootstrap:ro,Z [Install] diff --git a/example_configs/podman-quadlets/readme.md b/example_configs/podman-quadlets/readme.md new file mode 100644 index 0000000..bdd5649 --- /dev/null +++ b/example_configs/podman-quadlets/readme.md @@ -0,0 +1,61 @@ +## Installing the quadlet lldap user service + +The following assumes you have a working Podman installation and that you want to install lldap as a user service. + +It will create a systemd service for each of the quadlet files. As the files are supplied, the resulting services are: +- lldap.service +- lldap-db.service +- lldap-db-volume.service +- lldap-frontend-network.service +- lldap-backend-network.service + +Starting lldap.service and lldap-db.service always creates a fresh container. Stopping destroys the container. +Stopping the volume or network service **does not** destroy the associated volume or network. +If you want to customize the network, we suggest uncommenting the `NetworkDeleteOnStop` line in the network file before starting the lldap service for the first time. Once you have done so, stopping the network's services will allow you to modify the network properties. Otherwise, you must remove the network(s) manually with Podman. If you erase the volume, you will loose your database of users and will need to bootstrap lldap again. + +Starting `lldap.service` will start all the other services, but stopping it will not stop the other services. + +### Instructions + +- Copy `lldap-db.container`, `lldap.container`, `lldap-db.volume`, `lldap-frontend.network`, and `lldap-backend.network` to `~/.config/containers/systemd/` +- Adjust the line `Environment=LLDAP_LDAP_BASE_DN=dc=example,dc=com` in `lldap.container` to match your domain name. + - The default value assumes your domain is "example.com" +- Create the necessary secrets: `lldap-jwt-secret`, `lldap-key-seed`, and `lldap-ldap-user-pass`. + - Podman allows several different methods to create secrets; here, it will be done purely from the command line. Don't forget to replace the secret values with something actually secret. + ```bash + $ LC_ALL=C tr -dc 'A-Za-z0-9!#%&'\''()*+,-./:;<=>?@[\\]^_{|}~' ?@[\\]^_{|}~' --showsecret`. The value of the secret is in the output's "SecretData" field. +- At this point, you should be able to start the container. + - Test this with: + ```bash + $ podman --user daemon-reload + $ podman --user start lldap + $ podman --user status lldap + ``` + - Assuming it launched correctly, you should now stop it again. + ```bash + $ podman --user stop lldap + ``` +- Make any adjustments you feel are necessary to the network files. +- Now all that's left to do is the [bootstrapping process](../bootstrap/bootstrap.md#docker-compose): + - Prepare your bootstrapping config as for the docker-compose case in `~/containers/lldap`. + - Toward the end of the container section, uncomment the lines in `lldap.container` regarding the bootstrap process. + - Start the container: + ```bash + $ podman --user daemon-reload + $ podman --user start lldap + ``` + - Attach a terminal to the container, and run `bootstrap.sh`: + ```bash + $ podman exec -ti lldap bash + $ ./bootstrap.sh + ``` +- Once the bootstrapping is done, remove or comment out the lines you uncommented in the previous step, stop the unit, reload the daemon, and start it again. +- LLDAP should be available to any unit that includes the lldap-frontend network. + - If your outside-facing web server is in a quadlet or a podman container too, make sure they share a network, e.g., by adding `Network=lldap-frontend.network` in its quadlet file and making the necessary adjustments to the server configs. + - Your web server should then manage access to LLDAP from the outside world. +- If your web server is not running in a Podman container/quadlet, then you should publish a port to access LLDAP on localhost. For example, `PublishPort=127.0.0.1:17170:17170` will make the default port that LLDAP binds to inside the container available from the outside. + - There is no real reason to modify the port inside the container, but you might need to adjust the outside one if another service already binds it on your host system.