When a periphery agent container creates some resources (repos,stacks) in a bind mount these files are currently created as root. This makes reading/writing any of these files inconvenient if the user on the host is not root.
The container can be run with a non-root user by specify user: "UID:GID" or equivalent with docker run and the agent runs fine. It also creates resources with the correct permissions in this instance. However, the agent cannot access docker.sock due to it being owned by root:docker which is for security, I believe.
Please implement a way to allow control over file/folder permissions for resources touched by the agent, or, implement a way to use the container rootless that can still communicate with docker.
Some Thoughts
Enable SSL/HTTP communication with docker
(My preferred solution)
The crate used for docker communication, bollard, supports SSL/HTTP connections out of the box. The current connect_with_local_defaults() function could be try-caught (?) with a fallback to connect_with_http_defaults() and/or connect_with_ssl_defaults() -- both of which use environmental variables to initiate a connection which require no config change for the agent.
This would enable using docker-socket-proxy for communication which would solve non-root communication with docker.
chown with UID/GID from ENV
Allow a user to specify UID and GID in environmental variables and then chown files touched by the agent. This would allow the agent to continue to work as root while solving file permissions for bind mounts.
Originally created by @FoxxMD on GitHub (Sep 19, 2024).
Original GitHub issue: https://github.com/moghtech/komodo/issues/87
When a [`periphery` agent container](https://komo.do/docs/setup/connect-servers#install-the-periphery-agent---container) creates some resources (repos,stacks) in a bind mount these files are currently created as `root`. This makes reading/writing any of these files inconvenient if the user on the host is not root.
The container can be run with a non-root user by specify [`user: "UID:GID"`](https://docs.docker.com/reference/compose-file/services/#user) or equivalent with `docker run` and the agent runs fine. It also creates resources with the correct permissions in this instance. However, the agent **cannot** access `docker.sock` due to it being owned by `root:docker` which is for security, I believe.
Please implement a way to allow control over file/folder permissions for resources touched by the agent, or, implement a way to use the container rootless that can still communicate with docker.
### Some Thoughts
#### Enable SSL/HTTP communication with docker
(My preferred solution)
The crate used for docker communication, [`bollard`](https://github.com/fussybeaver/bollard?tab=readme-ov-file#http), supports SSL/HTTP connections out of the box. The current [`connect_with_local_defaults()`](https://github.com/mbecker20/komodo/blob/main/bin/periphery/src/docker.rs#L35) function could be try-caught (?) with a fallback to `connect_with_http_defaults()` and/or `connect_with_ssl_defaults()` -- both of which use environmental variables to initiate a connection which require no config change for the agent.
This would enable using [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) for communication which would solve non-root communication with docker.
#### `chown` with UID/GID from ENV
Allow a user to specify `UID` and `GID` in environmental variables and then `chown` files touched by the agent. This would allow the agent to continue to work as `root` while solving file permissions for bind mounts.
<!-- gh-comment-id:2418360143 -->
@mbecker20 commented on GitHub (Oct 17, 2024):
Now supports DOCKER_HOST env variable for use with [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy): https://github.com/mbecker20/komodo/releases/tag/v1.15.10
How would one go about configuring docker-socket-proxy and the DOCKER_HOST envvar, in order to enable the usage of a non-root user in the periphery agent?
Could you share your config @FoxxMD perhaps?
<!-- gh-comment-id:2740653846 -->
@paulora2405 commented on GitHub (Mar 20, 2025):
How would one go about configuring `docker-socket-proxy` and the `DOCKER_HOST` envvar, in order to enable the usage of a non-root user in the periphery agent?
Could you share your config @FoxxMD perhaps?
Expand the A Note on Security and Non-Root Periphery section (and Details section within for code example)
<!-- gh-comment-id:2741025664 -->
@FoxxMD commented on GitHub (Mar 20, 2025):
Hi @paulora2405 I wrote a blog post that covers how to do this, some gotchas I discovered, and sample code:
https://blog.foxxmd.dev/posts/migrating-to-komodo/#create-komodo-periphery-agents
Expand the `A Note on Security and Non-Root Periphery` section (and `Details` section within for code example)
@FoxxMD another detail that might be needed (in your blog post or perhaps in the documentation) is that you need to add the rootless path for docker.sock into the systemd config for periphery. I had to piece this together from other issues and posts until I figured it out.
In ~/.config/systemd/user/periphery.service I had to add this line:
but that didn't persist after a reboot for me, which is what brought me back here. Adding it to periphery.service seems like a more permanent solution (I think).
<!-- gh-comment-id:3550819498 -->
@willyp713 commented on GitHub (Nov 19, 2025):
@FoxxMD another detail that might be needed (in your blog post or perhaps in the documentation) is that you need to add the rootless path for `docker.sock` into the systemd config for periphery. I had to piece this together from other issues and posts until I figured it out.
In `~/.config/systemd/user/periphery.service` I had to add this line:
```
[Service]
Environment="DOCKER_HOST=unix:///run/user/1000/docker.sock"
```
Note that it required the unix:/// prefix or else the periphery agent would fail with an error about invalid URI scheme.
Another workaround is to create a symlink, such as:
`ln -s /run/user/1000/docker.sock /var/run/docker.sock`
but that didn't persist after a reboot for me, which is what brought me back here. Adding it to `periphery.service` seems like a more permanent solution (I think).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Originally created by @FoxxMD on GitHub (Sep 19, 2024).
Original GitHub issue: https://github.com/moghtech/komodo/issues/87
When a
peripheryagent container creates some resources (repos,stacks) in a bind mount these files are currently created asroot. This makes reading/writing any of these files inconvenient if the user on the host is not root.The container can be run with a non-root user by specify
user: "UID:GID"or equivalent withdocker runand the agent runs fine. It also creates resources with the correct permissions in this instance. However, the agent cannot accessdocker.sockdue to it being owned byroot:dockerwhich is for security, I believe.Please implement a way to allow control over file/folder permissions for resources touched by the agent, or, implement a way to use the container rootless that can still communicate with docker.
Some Thoughts
Enable SSL/HTTP communication with docker
(My preferred solution)
The crate used for docker communication,
bollard, supports SSL/HTTP connections out of the box. The currentconnect_with_local_defaults()function could be try-caught (?) with a fallback toconnect_with_http_defaults()and/orconnect_with_ssl_defaults()-- both of which use environmental variables to initiate a connection which require no config change for the agent.This would enable using docker-socket-proxy for communication which would solve non-root communication with docker.
chownwith UID/GID from ENVAllow a user to specify
UIDandGIDin environmental variables and thenchownfiles touched by the agent. This would allow the agent to continue to work asrootwhile solving file permissions for bind mounts.@mbecker20 commented on GitHub (Oct 17, 2024):
Now supports DOCKER_HOST env variable for use with docker-socket-proxy: https://github.com/mbecker20/komodo/releases/tag/v1.15.10
@paulora2405 commented on GitHub (Mar 20, 2025):
How would one go about configuring
docker-socket-proxyand theDOCKER_HOSTenvvar, in order to enable the usage of a non-root user in the periphery agent?Could you share your config @FoxxMD perhaps?
@FoxxMD commented on GitHub (Mar 20, 2025):
Hi @paulora2405 I wrote a blog post that covers how to do this, some gotchas I discovered, and sample code:
https://blog.foxxmd.dev/posts/migrating-to-komodo/#create-komodo-periphery-agents
Expand the
A Note on Security and Non-Root Peripherysection (andDetailssection within for code example)@willyp713 commented on GitHub (Nov 19, 2025):
@FoxxMD another detail that might be needed (in your blog post or perhaps in the documentation) is that you need to add the rootless path for
docker.sockinto the systemd config for periphery. I had to piece this together from other issues and posts until I figured it out.In
~/.config/systemd/user/periphery.serviceI had to add this line:Note that it required the unix:/// prefix or else the periphery agent would fail with an error about invalid URI scheme.
Another workaround is to create a symlink, such as:
ln -s /run/user/1000/docker.sock /var/run/docker.sockbut that didn't persist after a reboot for me, which is what brought me back here. Adding it to
periphery.serviceseems like a more permanent solution (I think).