Pandore/homarr
Public Access
1
0 Fork 0
Code Actions Activity

docs: streamline release v2 documentation (#6760)

Browse Source
This commit is contained in:
Thomas authored and GitHub committed 2026-09-03 17:03:10 +02:00
1 parent ac62e5bfd6
commit b3aa6155cc
163 files changed
+2908 -4208
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

apps/docs/docs/integrations/docker/index.mdx
+83 -272
View File
@@ -1,114 +1,25 @@
---
title: "Docker"
description: "Docker is a platform where you can run your applications in containers, allowing for easy deployment and management of applications."
description: "Connect Homarr to Docker-compatible container engines."
hide_title: true
---
import { IntegrationHeader } from "@site/src/components/integrations/header";
import { IntegrationCapabilites } from "@site/src/components/integrations/widgets";
import { IntegrationSecrets } from "@site/src/components/integrations/secrets";
import { IconBrandDocker, IconTool } from "@tabler/icons-react";
import { dockerIntegration } from ".";
import { dockerContainersWidget } from "@site/docs/widgets/docker-containers";
<IntegrationHeader integration={dockerIntegration} categories={["Containers"]} />
### Widgets & Capabilities
### Widgets and capabilities
<IntegrationCapabilites
items={[
{
widget: dockerContainersWidget,
note: "This widget can only be used with administrator privileges",
},
]}
/>
<IntegrationCapabilites items={[{ widget: dockerContainersWidget, note: "Requires administrator access" }]} />
## Connecting Docker to Homarr
Docker endpoints are configured with environment variables rather than under **Management → Integrations**.
Docker connections come directly from Homarr's environment variables. They are automatically available in the Docker management table and Docker widget; you do not create a Docker integration under **Management → Integrations**.
## Local socket
If Homarr runs directly on a host with Docker installed, it uses `/var/run/docker.sock` by default. When Homarr runs in a container, mount the [Docker socket](https://docs.docker.com/engine/security/protect-access/) into it so Homarr can interact with Docker.
In Docker Compose, you can simply add this line:
```yaml {10}
#---------------------------------------------------------------------#
# 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](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/<uid>/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 <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`.
:::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:
Mount the Docker socket into the Homarr container:
```yaml
services:
@@ -116,12 +27,34 @@ services:
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
- ./homarr/appdata:/appdata
```
For remote socket proxies, list the hostnames and matching ports in the same order:
`/var/run/docker.sock` is the default. For other in-container paths, set a comma-separated list:
```yaml
environment:
DOCKER_SOCKET_PATHS: /var/run/docker.sock,/var/run/podman.sock
```
## Podman
Homarr uses Podman's Docker-compatible API. Start the Podman socket, mount it, and include its in-container path in
`DOCKER_SOCKET_PATHS`.
For rootless Podman:
```sh
systemctl --user enable --now podman.socket
podman info --format '{{.Host.RemoteSocket.Path}}'
```
Run Homarr as the user that owns the socket. On SELinux systems, Podman may require `security_opt: [label=disable]` for
the Homarr container. Rootful Podman normally exposes `/run/podman/podman.sock`.
## Remote endpoints
For Docker socket proxies, list aligned hostnames and ports:
```yaml
environment:
@@ -129,193 +62,71 @@ environment:
DOCKER_PORTS: 2375,2375
```
Homarr automatically discovers each comma-separated entry as a separate Docker environment. All environments are selected by default; the Docker widget lets you select one or more without any additional setup.
:::warning Plaintext Docker API
Unauthenticated Docker TCP provides control of the Docker host. Keep a socket proxy on a private network or use TLS.
:::warning[Plaintext TCP]
Plaintext Docker TCP can grant unauthenticated control of the Docker host. Prefer a local socket, a least-privilege socket proxy on a private Docker network, or TLS.
:::
### Advanced endpoint configuration
Most users should use the comma-separated variables above. Use `DOCKER_ENDPOINTS` only when you need custom names, TLS, or restricted capabilities. It is a JSON array where every endpoint declares its identity, transport, and capabilities:
Use `DOCKER_ENDPOINTS` for named endpoints, TLS, or restricted capabilities:
```yaml
services:
homarr:
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./docker-ca.pem:/run/secrets/docker-ca.pem:ro
environment:
DOCKER_ENDPOINTS: >-
[
{
"id": "local",
"name": "Local Docker",
"kind": "docker",
"transport": { "type": "socket", "path": "/var/run/docker.sock" },
"capabilities": ["inventory", "logs", "lifecycle", "remove"]
},
{
"id": "remote-read-only",
"name": "Production inventory",
"kind": "docker",
"transport": {
"type": "tls",
"host": "docker.example.com",
"port": 2376,
"caPath": "/run/secrets/docker-ca.pem"
},
"capabilities": ["inventory", "logs"]
}
]
environment:
DOCKER_ENDPOINTS: >-
[
{
"id": "local",
"name": "Local Docker",
"kind": "docker",
"transport": { "type": "socket", "path": "/var/run/docker.sock" },
"capabilities": ["inventory", "logs", "lifecycle", "remove"]
},
{
"id": "production",
"name": "Production inventory",
"kind": "docker",
"transport": {
"type": "tls",
"host": "docker.example.com",
"port": 2376,
"caPath": "/run/secrets/docker-ca.pem"
},
"capabilities": ["inventory", "logs"]
}
]
```
The stable `id` keeps containers from different endpoints distinct. `name` is shown in the interface, and `kind` can be `docker` or `podman`. Every endpoint must include the `inventory` capability; optionally add `logs`, `lifecycle`, and `remove`. Homarr hides or disables actions the endpoint does not allow and also enforces the same capabilities on the server.
Each endpoint requires a stable `id`, display `name`, `kind` (`docker` or `podman`), transport, and the `inventory`
capability. Optional capabilities are `logs`, `lifecycle`, and `remove`.
Supported transports are:
| Transport | Required values |
| --------- | ----------------------------------------------------------------------------------- |
| `socket` | Absolute in-container `path` |
| `tls` | `host`, `port`, absolute `caPath`; optional `certPath` and `keyPath` for mutual TLS |
| `tcp` | `host`, `port`, and `allowInsecure: true` |
- `socket`: an absolute in-container `path`
- `tls`: `host`, `port`, and an absolute `caPath`; add both `certPath` and `keyPath` for mutual TLS
- `tcp`: `host`, `port`, and the explicit acknowledgement `allowInsecure: true`
`DOCKER_ENDPOINTS` takes precedence over the socket, hostname, and port lists.
The structured configuration refuses TCP unless `allowInsecure` is explicitly set to `true`. When `DOCKER_ENDPOINTS` is set, it takes precedence over `DOCKER_SOCKET_PATHS`, `DOCKER_HOSTNAMES`, and `DOCKER_PORTS`.
## Use in Homarr
### Managing your Docker containers within Homarr
The Docker management page lists containers from every configured endpoint and can show logs, resource use, and
permitted lifecycle actions. The Docker widget can include all endpoints or a selected subset.
Homarr allows you to interact with Docker containers running on your system.
The collapsed **Assisted Docker setup** helper optionally compares visible containers with your existing Homarr apps and integrations. Open it only when you want setup suggestions; it never blocks normal container management. Every service stays distinct by Docker endpoint and container ID, including multiple containers that use the same integration type.
Assisted setup compares discovered containers with existing apps and integrations. Discovery is read-only; creating or
updating a Homarr resource still requires confirmation. If one endpoint is unavailable, containers from healthy
endpoints remain visible.
Homarr can show a service as:
The `homarr.hide` label excludes a container. Other `homarr.*` labels can provide apps, integrations, groups, and widgets
during onboarding; see [Docker label discovery](../docker-labels).
- **Ready to connect** when its image or name matches a supported integration
- **New service** when it can be added as an app but no integration is recognized
- **Already represented** or **Linked** when an app or integration already matches
- **Address changed** when a service appears to match an integration but its reachable address has changed
## Security
Set the usual server address once, then choose whether services normally use different ports, subdomains, or paths. Homarr uses that pattern to prefill every detected service. Each suggestion has one editable URL field with the generated and Docker-reported addresses available as autocomplete options, so you can select a suggestion or type any address directly.
A Docker or Podman socket grants extensive host control. Prefer a least-privilege socket proxy when lifecycle access is
not required.
:::info[Review before changing]
Service discovery is read-only. Homarr never creates or changes an app or integration automatically. **Set up integration** opens the standard prefilled integration form, while **Create app** opens the existing Docker app form, so you can review and confirm the final setup.
:::
Homarr needs `CONTAINERS=1` for inventory and `POST=1` for standard lifecycle actions with common proxies. LSIO's proxy
can instead expose `ALLOW_START=1`, `ALLOW_STOP=1`, and `ALLOW_RESTARTS=1` while keeping `POST=0`; removal is then
unavailable.
Suggestions appear as a compact task list. Expand an item only when you want to edit its URL or inspect relevant setup statuses. Use the filters to focus on services that need attention or those already represented in Homarr. Refresh runs discovery again. Dismissed suggestions are stored in the current browser using their endpoint-qualified service identity and can be restored from the same helper. If multiple existing items could match, Homarr marks the result as ambiguous and does not choose one automatically.
Compact status icons summarize the setup information Homarr can act on. Unknown and non-applicable runtime layers are omitted to keep the helper focused; use the integration form's connection test or the relevant board action for live diagnostics.
If one Docker endpoint is unavailable, Homarr reports that endpoint while continuing to show services from healthy endpoints. An unavailable endpoint is not treated as an empty Docker installation.
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:
![Container and Image Search](img/container-and-image-search.png)
#### 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.
#### Choosing Docker environments in the widget
The Docker widget can show one or more configured Docker environments. Leave **Docker environments** empty to include every endpoint, which is also the default for existing widgets. Selecting one or more entries limits container and statistics requests to those endpoints.
#### 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:
![Dialog for addding apps to Homarr](img/add-to-homarr-dialog.png)
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.
![Apps added from containers](img/add-to-homarr-apps.png)
### Container labels
`homarr.hide` excludes a container from the Docker Containers widget, tools page, and onboarding discovery whenever the
label is present.
During first-run onboarding, Homarr can also discover apps, integrations, groups, and compatible widgets from
`homarr.*` labels, with Homepage labels as a fallback. See the complete [Docker label reference](/docs/integrations/docker-labels).
### 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](https://github.com/linuxserver/docker-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):
```yaml
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:
```yaml
networks:
- socket-proxy
```
3. Finally, if it is present, remove the default docker socket connection under `volumes` in the homarr service.
Add Homarr to the proxy's Docker network and configure its service name and port with `DOCKER_HOSTNAMES` and
`DOCKER_PORTS`.