From 49d0f1a141c72c21bafef778d8faa035d92317c3 Mon Sep 17 00:00:00 2001 From: Thomas Date: Wed, 29 Jul 2026 16:53:29 +0200 Subject: [PATCH] docs: explain Podman socket setup (#6487) * docs: explain Podman socket setup * docs: clarify Podman runtime requirements * docs: complete Podman compose examples --- .../advanced/environment-variables/index.mdx | 6 +- apps/docs/docs/integrations/docker/index.mdx | 68 +++++++++++++++++++ 2 files changed, 71 insertions(+), 3 deletions(-) diff --git a/apps/docs/docs/advanced/environment-variables/index.mdx b/apps/docs/docs/advanced/environment-variables/index.mdx index f1a70b371..ad249e734 100644 --- a/apps/docs/docs/advanced/environment-variables/index.mdx +++ b/apps/docs/docs/advanced/environment-variables/index.mdx @@ -55,9 +55,9 @@ A random secret can be generated by using the following command: `openssl rand - | Environment Variable | Description | Possible values | Default | | ------------------------ | ----------- | --------------- | ------- | -| ``DOCKER_HOSTNAMES`` | Comma seperated list of hostnames to connect to | For example `localhost,docker.example.com` | - | -| ``DOCKER_PORTS`` | Comma seperated list of ports to connect to | For example `2375,2376` | - | -| ``DOCKER_SOCKET_PATHS`` | Comma seperated list of paths to sockets | For example `/var/run/docker.sock,/run/user/1000/podman/podman.sock` | - | +| ``DOCKER_HOSTNAMES`` | Comma-separated list of hostnames to connect to | For example `localhost,docker.example.com` | - | +| ``DOCKER_PORTS`` | Comma-separated list of ports to connect to | For example `2375,2376` | - | +| ``DOCKER_SOCKET_PATHS`` | Comma-separated list of mounted Docker-compatible socket paths. See the [Docker and Podman integration guide](/docs/integrations/docker) | For example `/var/run/docker.sock,/var/run/podman.sock` | - | ## Database | Environment Variable | Description | Possible values | Default | diff --git a/apps/docs/docs/integrations/docker/index.mdx b/apps/docs/docs/integrations/docker/index.mdx index e48c46e9b..2af43c67e 100644 --- a/apps/docs/docs/integrations/docker/index.mdx +++ b/apps/docs/docs/integrations/docker/index.mdx @@ -55,6 +55,74 @@ services: With docker run, add this parameter: `-v /var/run/docker.sock:/var/run/docker.sock`. In Windows, you'll need to adjust the slashes: `-v //var/run/docker.sock:/var/run/docker.sock` +### Using Podman + +On Linux, Homarr can connect to Podman's [Docker-compatible API](https://docs.podman.io/en/latest/markdown/podman-system-service.1.html). +The Podman API socket must be running and mounted into the Homarr container. +The socket grants full access to Podman, including arbitrary code execution as the user running the API, so only mount it into trusted containers. + +For rootless Podman, enable the socket for the user that runs Homarr: + +```bash +systemctl --user enable --now podman.socket +``` + +The rootless socket is located at `$XDG_RUNTIME_DIR/podman/podman.sock` (usually `/run/user//podman/podman.sock`). +You can confirm the path with: + +```bash +podman info --format '{{.Host.RemoteSocket.Path}}' +``` + +Mount that socket into the Homarr container and point `DOCKER_SOCKET_PATHS` to its path **inside** the container: + +```yaml +services: + homarr: + container_name: homarr + image: ghcr.io/homarr-labs/homarr:latest + restart: unless-stopped + volumes: + - ${XDG_RUNTIME_DIR}/podman/podman.sock:/var/run/podman.sock + - ./homarr/appdata:/appdata + environment: + SECRET_ENCRYPTION_KEY: your_64_character_hex_string + DOCKER_SOCKET_PATHS: /var/run/podman.sock + ports: + - "7575:7575" +``` + +Start Homarr with `podman compose up -d`. +Run the compose project as the same user that owns the rootless Podman socket so `$XDG_RUNTIME_DIR` resolves to the correct path. +To keep the user socket available after logout and across reboots, enable lingering with `loginctl enable-linger `. + +For rootful Podman, enable the system socket with `sudo systemctl enable --now podman.socket`. +Its default path is `/run/podman/podman.sock`; mount that path instead and start Homarr with `sudo podman compose up -d`. + +:::note SELinux +On systems with SELinux enabled, Podman's documentation recommends disabling label separation for a container that accesses the API socket. +Add the following to the Homarr service: + +```yaml +security_opt: + - label=disable +``` + +::: + +You can connect Homarr to multiple Docker-compatible sockets by mounting each socket and listing their in-container paths, separated by commas: + +```yaml +services: + homarr: + image: ghcr.io/homarr-labs/homarr:latest + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ${XDG_RUNTIME_DIR}/podman/podman.sock:/var/run/podman.sock + environment: + DOCKER_SOCKET_PATHS: /var/run/docker.sock,/var/run/podman.sock +``` + ### Managing your Docker containers within Homarr Homarr allows you to interact with Docker containers running on your system. Each container row has an action menu with the following options: