Skip to content

Commit

Permalink
docs: add documentation for connecting to Docker Socket Proxies (#184)
Browse files Browse the repository at this point in the history
  • Loading branch information
itskagee authored Jan 29, 2025
1 parent 010b37b commit a5f0ba5
Showing 1 changed file with 49 additions and 2 deletions.
51 changes: 49 additions & 2 deletions docs/integrations/containers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,59 @@ They are then available in the app list and can be used as normally added apps.
![Apps added from containers](img/containers/add-to-homarr-apps.png)

## Security
Mounting docker sockets can be risk, as they permit full control over your docker service.
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.
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.

0 comments on commit a5f0ba5

Please sign in to comment.