homelab/active/container_keycloak/keycloak.md

Podman keycloak

• Podman keycloak
  • Setup keycloak Project
  • Install Keycloak with Docker
  • Install Keycloak with Podman
    • Create the keycloak user
    • Write the keycloak compose spec
      • A Note on Volumes
    • Convert keycloak compose spec to quadlets
    • Create any container-mounted directories
    • Start and enable your systemd quadlet
    • Expose keycloak
      • firewalld
  • Backup keycloak
  • Upgrade keycloak
    • Upgrade Quadlets
  • Uninstall
  • Notes
    • SELinux

Setup keycloak Project

• Copy and rename this folder to active/container_keycloak
• Find and replace keycloak with the name of the service.
• Create the rootless user to run the podman containers
• Write the compose.yaml spec for your service
• Convert the compose.yaml spec to a quadlet
• Install the quadlet on the podman server
• Expose the quadlet service
• Install a backup service and timer

Install Keycloak with Docker

https://www.keycloak.org/getting-started/getting-started-docker

# Test in dev mode
docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.4.7 start-dev

Install Keycloak with Podman

Create the keycloak user

# SSH into your podman server as root
useradd keycloak
loginctl enable-linger $(id -u keycloak)
systemctl --user --machine=keycloak@.host enable podman-restart
systemctl --user --machine=keycloak@.host enable --now podman.socket
mkdir -p /home/keycloak/.config/containers/systemd

Write the keycloak compose spec

https://www.keycloak.org/getting-started/getting-started-podman

# Based on the example
podman run \
-p 127.0.0.1:8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
quay.io/keycloak/keycloak:26.4.5 start-dev

A Note on Volumes

Named volumes are stored at /home/keycloak/.local/share/containers/storage/volumes/.

Convert keycloak compose spec to quadlets

Run the following to convert a compose.yaml into the various .container files for systemd:

# Generate the systemd service
podman run \
--security-opt label=disable \
--rm \
-v $(pwd)/active/container_keycloak/:/compose \
-v $(pwd)/active/container_keycloak/quadlets:/quadlets \
quay.io/k9withabone/podlet \
-f /quadlets \
-i \
--overwrite \
compose /compose/compose.yaml

# Copy the files to the server
export PODMAN_SERVER=
scp -r active/container_keycloak/quadlets/. $PODMAN_SERVER:/home/keycloak/.config/containers/systemd/
ssh $PODMAN_SERVER chown -R keycloak:keycloak /home/keycloak/.config/containers/systemd/

Create any container-mounted directories

SSH into your podman server as root:

machinectl shell keycloak@
podman unshare
mkdir some_volume
# Chown to the namespaced user with UID 1000
# This will be some really obscure UID outside the namespace
# This will also solve most permission denied errors
chown -R 1000:1000 some_volume

Start and enable your systemd quadlet

SSH into your podman server as root:

machinectl shell keycloak@
systemctl --user daemon-reload
systemctl --user restart keycloak
# Enable auto-update service which will pull new container images automatically every day
systemctl --user enable --now podman-auto-update.timer

Expose keycloak

1. If you need a domain, follow the DDNS instructions
2. For a web service, follow the Caddy instructions
3. Finally, follow your OS's guide for opening ports via its firewall service.

firewalld

# command to get current active zone and default zone
firewall-cmd --get-active-zones
firewall-cmd --get-default-zone

# command to open 443 on tcp
firewall-cmd --permanent --zone=<zone> --add-port=443/tcp

# command to open 80 and 443 on tcp and udp
firewall-cmd --permanent --zone=<zone> --add-port={80,443}/{tcp,udp}

# command to list available services and then open http and https
firewall-cmd --get-services
firewall-cmd --permanent --zone=<zone> --add-service={http,https}

Backup keycloak

Follow the Borg Backup instructions

Upgrade keycloak

Upgrade Quadlets

Upgrades should be a repeat of writing the compose spec and installing the quadlets

export PODMAN_SERVER=
scp -r quadlets/. $PODMAN_SERVER$:/home/keycloak/.config/containers/systemd/
ssh keycloak systemctl --user daemon-reload
ssh keycloak systemctl --user restart keycloak

Uninstall

# Stop the user's services
systemctl --user disable podman-restart
podman container stop --all
systemctl --user disable --now podman.socket
systemctl --user disable --now podman-auto-update.timer

# Delete the user (this won't delete their home directory)
# userdel might spit out an error like:
# userdel: user keycloak is currently used by process 591255
# kill those processes and try again
userdel keycloak

Notes

SELinux

https://blog.christophersmart.com/2021/01/31/podman-volumes-and-selinux/

:z allows a container to share a mounted volume with all other containers.

:Z allows a container to reserve a mounted volume and prevents any other container from accessing.