133 lines
4.6 KiB
Plaintext
133 lines
4.6 KiB
Plaintext
---
|
|
title: "Docker"
|
|
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 { dockerIntegration } from ".";
|
|
import { dockerContainersWidget } from "@site/docs/widgets/docker-containers";
|
|
|
|
<IntegrationHeader integration={dockerIntegration} categories={["Containers"]} />
|
|
|
|
### Widgets and capabilities
|
|
|
|
<IntegrationCapabilites items={[{ widget: dockerContainersWidget, note: "Requires administrator access" }]} />
|
|
|
|
Docker endpoints are configured with environment variables rather than under **Management → Integrations**.
|
|
|
|
## Local socket
|
|
|
|
Mount the Docker socket into the Homarr container:
|
|
|
|
```yaml
|
|
services:
|
|
homarr:
|
|
image: ghcr.io/homarr-labs/homarr:latest
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock
|
|
- ./homarr/appdata:/appdata
|
|
```
|
|
|
|
`/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:
|
|
DOCKER_HOSTNAMES: docker-proxy-home,docker-proxy-lab
|
|
DOCKER_PORTS: 2375,2375
|
|
```
|
|
|
|
:::warning Plaintext Docker API
|
|
|
|
Unauthenticated Docker TCP provides control of the Docker host. Keep a socket proxy on a private network or use TLS.
|
|
|
|
:::
|
|
|
|
Use `DOCKER_ENDPOINTS` for named endpoints, TLS, or restricted capabilities:
|
|
|
|
```yaml
|
|
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"]
|
|
}
|
|
]
|
|
```
|
|
|
|
Each endpoint requires a stable `id`, display `name`, `kind` (`docker` or `podman`), transport, and the `inventory`
|
|
capability. Optional capabilities are `logs`, `lifecycle`, and `remove`.
|
|
|
|
| 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` |
|
|
|
|
`DOCKER_ENDPOINTS` takes precedence over the socket, hostname, and port lists.
|
|
|
|
## Use in 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.
|
|
|
|
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.
|
|
|
|
The `homarr.hide` label excludes a container. Other `homarr.*` labels can provide apps, integrations, groups, and widgets
|
|
during onboarding; see [Docker label discovery](/docs/integrations/docker-labels).
|
|
|
|
## Security
|
|
|
|
A Docker or Podman socket grants extensive host control. Prefer a least-privilege socket proxy when lifecycle access is
|
|
not required.
|
|
|
|
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.
|
|
|
|
Add Homarr to the proxy's Docker network and configure its service name and port with `DOCKER_HOSTNAMES` and
|
|
`DOCKER_PORTS`.
|