Podman Install

This walkthrough follows Keeper’s official “Docker Compose Install” instructions but modified for Podman.

Before you start

What you need
Minimum
Notes

Linux server

RHEL 9 / Alma 9 / Rocky 9 / Fedora 39 OR Ubuntu 24.04 / Debian 12

Any modern distro that ships Podman 5+ works.

Packages

podman & podman‑compose

Installed in Step 3.

Network

One free TCP port (8080 is used below)

If you want HTTPS later, you’ll also open 80 & 443.

Step 1. Create a working folder and save the Compose file

  • Sign in to your server and run:

sudo mkdir -p /opt/kcm && cd /opt/kcm
  • In a browser, visit the Docker Compose Install page

  • Scroll to Step 2 — Create Docker Compose File.

  • Copy the YAML block and paste the text into the file /opt/kcm/docker‑compose.yml with a text editor.


Step 2. Download the hardened seccomp profile

Keeper’s docs place this file automatically if you use their install script. With Compose we pull it ourselves:

sudo mkdir -p /etc/kcm-setup
sudo podman run --rm --entrypoint=/bin/cat \
  docker.io/keeper/guacd:2 \
  /opt/keeper/share/guacd/docker-seccomp.json \
  | sudo tee /etc/kcm-setup/guacd-docker-seccomp.json

The command starts a temporary container, reads the JSON file inside, and saves it on the host.


Step 3. Install Podman & helper tools

RHEL / Alma / Rocky / Fedora

sudo dnf install -y podman podman-compose firewalld haveged
sudo systemctl enable --now haveged   # adds extra entropy for SSL

Ubuntu / Debian

sudo apt update && sudo apt install -y podman podman-compose firewalld haveged
sudo systemctl enable --now haveged

Check: podman --version should show 5.x or newer.


Step 4. Modify the Compose file for Podman

Open /opt/kcm/docker‑compose.yml again and make these small edits:

  1. Security profile (under the guacd service):

    security_opt:
      - seccomp:/etc/kcm-setup/guacd-docker-seccomp.json
  2. SELinux hosts only (RHEL/Fedora): add :Z after each bind‑mount, for example: - "common-storage:/var/lib/guacamole:rw,Z"

  3. Optional: Replace any :latest tags with the current major tag :2 (e.g. keeper/guacamole:2).

That’s it—no other changes are required.


Step 5. Start Keeper Connection Manager

cd /opt/kcm
sudo podman-compose up -d  # add --time 30 if the DB needs extra init time

Check that three containers are Up:

podman ps --format "{{.Names}}  {{.Status}}  {{.Ports}}"

Open your browser to http://<server‑IP>:8080. You should see the Keeper login page.


Step 6. Open the firewall (RHEL/Fedora)

sudo systemctl enable --now firewalld
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

(Ubuntu’s UFW or Debian’s nftables users perform the equivalent rule.)


Step 7. Set up automatic startup

sudo podman generate systemd --name kcm_guacamole_1 --files --new
sudo podman generate systemd --name kcm_guacd_1      --files --new
sudo podman generate systemd --name kcm_db_1         --files --new
sudo mv *.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now container-kcm_guacamole_1.service \
                       container-kcm_guacd_1.service \
                       container-kcm_db_1.service

Now KCM will survive server reboots without any extra commands.


Step 8. First‑run checks

What to test
Command
Expected result

Local health

curl -f http://localhost:8080/

Returns HTML with <title>Guacamole</title>

Container status

podman ps

All three containers show Up

Remote access

Browser → http://<server-IP>:8080

Shows login page


Troubleshooting

Problem you see

Likely reason

Quick remedy

Browser says “Connection timed out”

Server firewall still blocking 8080 or you ran Podman rootless (port bound to 127.0.0.1)

Rootful: run the firewall‑cmd lines in Step 6. Rootless: run KCM on 8080 and put nginx/HAProxy in front on port 80/443.

404 Not Found at /guacamole

The UI sits at / by default.

Go to http://host:8080/ or set GUACAMOLE_CONTEXT_PATH=guacamole in the guacamole service.

Permission denied errors on Fedora/RHEL

Missing SELinux label

Add :Z to each volume line in docker-compose.yml, then podman-compose down && podman-compose up -d.

Service dies after a reboot

Podman‑Compose ignores restart:

Follow Step 7 to generate systemd units.

DB keeps restarting

Passwords don’t match or volume wiped

Check the POSTGRES_PASSWORD and other DB env vars are the same in both db and guacamole services.

When in doubt, run podman logs <container-name> and read the last few lines—it usually tells you what went wrong.


You’re done! Keeper Connection Manager is now running on Podman without Docker. Enjoy your lighter, daemon‑free setup.


Last updated

Was this helpful?