Docker

Containers

Docker is a platform where you can run your applications in containers, allowing for easy deployment and management of applications.

Widgets & Capabilities

Docker statsStats of your containersThis widget can only be used with administrator privileges

Details

Enabling the Docker integration

This integration must first be enabled. If you directly run on the host system and you have docker installed, it will be enabled by default. Otherwise, you'll need to mount the docker socket to the Homarr container, so Homarr can interact with the Docker service.

In Docker Compose, you can simply add this line:

#---------------------------------------------------------------------#
#     Homarr - A simple, yet powerful dashboard for your server.      #
#---------------------------------------------------------------------#
services:
  homarr:
    container_name: homarr
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # <--- add this line here!
      - ./homarr/appdata:/appdata
    environment:
      - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
    ports:
      - '7575:7575'

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. 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:

systemctl --user enable --now podman.socket

The rootless socket is located at $XDG_RUNTIME_DIR/podman/podman.sock (usually /run/user/<uid>/podman/podman.sock). You can confirm the path with:

podman info --format '{{.Host.RemoteSocket.Path}}'

Mount that socket into the Homarr container and point DOCKER_SOCKET_PATHS to its path inside the container:

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 <user>.

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.

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:

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:

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:

• View logs - opens a dedicated logs page with a live terminal
• Start - start a stopped container
• Stop - stop a running container
• Restart - restart a container
• Remove - remove a container
• Add to Homarr - create a bookmark app from the container

You can also search and filter containers by container or image name:

Viewing container logs

You can view the real-time logs of any container by selecting View logs from the row action menu. This opens a dedicated page with an xterm.js terminal that streams the container's log output.

CPU and Memory columns

The Docker management table supports optional CPU usage and Memory usage columns. These columns are hidden by default and can be toggled on from the table column visibility settings.

Add apps from containers

Homarr also lets you add apps from containers. You can simply select all containers you want to add an app for and then click the Add to Homarr button. This will open a dialog where you can specify the web addresses for all of them:

Once you've changed the web addresses, click the Add button to add the apps to Homarr. They are then available in the app list and can be used as normally added apps.

Configuration

Currently Homarr supports one label for configuration of the containers:

• homarr.hide: If set to any value, the container will be hidden from the Docker Containers widget and tools page.

Security

Mounting docker sockets can be risky, as they permit full control over your docker service. As an example, a thread actor could abuse Homarr use the socket to start, stop or delete containers on your system.

Therefore we recommend the usage of a socket proxy, which can prohibit certain actions. A few examples include:

• https://github.com/linuxserver/docker-socket-proxy
• https://github.com/Tecnativa/docker-socket-proxy

See documentation of the respective proxies on how to configure them. Homarr may behave in unexpected ways when you use proxies.

Permissions

Homarr needs the following permissions from the Docker API:

• Containers/Start
• Containers/Stop
• Containers/Restart
• Containers/Remove

For socket proxies, you will need these permissions:

• CONTAINERS=1
• POST=1

Caution: POST access is security critical as it provides extensive capabilities to modify your docker environment. Please leave it disabled if you're concerned about this.

As a workaround, you can use LSIO's socket proxy and set the following:

• ALLOW_START=1
• ALLOW_STOP=1
• ALLOW_RESTARTS=1

These will work even with POST=0.

You lose the ability to remove containers, but start, stop and restarts should work just fine.

Connecting to Docker via Socket Proxies

To connect to Docker via a socket proxy, you'll need to add these two environment variables in the compose file:

• DOCKER_HOSTNAMES=<name of the socket proxy container>
• DOCKER_PORTS=<socket proxy port, usually 2375>

Refer: https://homarr.dev/docs/advanced/environment-variables/

You will also need to add Homarr to the network of your socket proxy. You can do it like this:

1. Add the network to your compose file (with appropriate changes):

networks:
  socket-proxy:
    name: socket-proxy # <--- change this to the name of the network as set up by the socket proxy
    external: true

2. Add the network to the homarr service in the compose file:

networks:
  - socket-proxy

3. Finally, if it is present, remove the default docker socket connection under volumes in the homarr service.