feat!: Run Device Agent in container as unpriviledged user (#565)

Co-authored-by: Ben Hardill <ben@flowforge.com>

Author: ppawlowski

.github/workflows/build.yml

@@ -6,11 +6,15 @@ on:
     paths-ignore:
       - '.github/workflows/installer-build.yaml'
       - 'installer/**'
+      - 'docker/**'
+      - '.github/workflows/docker-build.yaml'
   pull_request:
     branches: [ main ]
     paths-ignore:
       - '.github/workflows/installer-build.yaml'
       - 'installer/**'
+      - 'docker/**'
+      - '.github/workflows/docker-build.yaml'
 
 jobs:
   build:

README.md

@@ -44,6 +44,38 @@ When running with the container you will need to mount the `device.yml` obtained
 docker run --mount type=bind,src=/path/to/device.yml,target=/opt/flowfuse-device/device.yml -p 1880:1880 flowfuse/device-agent:latest
 ```
 
+Alternatively, you can mount the entire configuration directory:
+
+```bash
+docker run --mount type=bind,src=/path/to/config/dir,target=/opt/flowfuse-device -p 1880:1880 flowfuse/device-agent:latest
+```
+
+> [!IMPORTANT]
+> **Breaking change in 4.0.0 — the container now runs as a non-root user.**
+>
+> From `4.0.0` the image runs as the unprivileged `flowfuse` user (`UID 2000` /
+> `GID 2000`) instead of `root`. If you bind-mount a host directory for state
+> (e.g. at `/opt/flowfuse-device` to persist `device.yml`, the `project/`
+> directory and the module cache), that directory must be **writable by UID
+> 2000**, otherwise the agent will fail to start with a permissions error.
+>
+> Before upgrading, change the ownership of the mounted directory on the host:
+>
+> ```bash
+> sudo chown -R 2000:2000 /path/to/config/dir
+> ```
+>
+> Alternatively, run the container as a UID that already owns the host
+> directory (the agent only requires the state directory to be writable by the
+> runtime user):
+>
+> ```bash
+> docker run --user $(id -u):$(id -g) ... flowfuse/device-agent:latest
+> ```
+>
+> If you build the image yourself, the user and group IDs can be customised with
+> the `FF_UID` and `FF_GID` build arguments.
+
 ## Configuration
 
 The agent configuration is provided by a `device.yml` file within its working

docker/Dockerfile

@@ -2,15 +2,20 @@ ARG NODE_VERSION=20
 FROM node:${NODE_VERSION}-alpine
 
 ARG VERSION=latest
+ARG FF_UID=2000
+ARG FF_GID=2000
 
 RUN apk add --no-cache --virtual buildtools build-base linux-headers udev python3 openssl
 
-RUN npm install -g npm
+RUN addgroup -g ${FF_GID} -S flowfuse \
+    && adduser -u ${FF_UID} -S -G flowfuse -h /opt/flowfuse-device flowfuse \
+    && mkdir -p /opt/flowfuse-device \
+    && chown -R "${FF_UID}":"${FF_GID}" /opt/flowfuse-device
 
-RUN mkdir -m 777 -p /opt/flowfuse-device
-RUN npm config set cache /opt/flowfuse-device/.npm --global
-RUN npm install -g @flowfuse/device-agent@${VERSION} --omit=dev
-RUN chmod -R 777 /opt/flowfuse-device/.npm
+RUN npm install -g npm \
+    && npm config set cache /opt/flowfuse-device/.npm --global \
+    && npm install -g @flowfuse/device-agent@${VERSION} --omit=dev \
+    && chown -R ${FF_UID}:${FF_GID} /opt/flowfuse-device
 
 EXPOSE 1880
 
@@ -23,4 +28,8 @@ LABEL org.label-schema.name="FlowFuse Device Agent" \
     authors="FlowFuse Inc."
 
 
+ENV HOME=/opt/flowfuse-device
+
+USER flowfuse
+
 CMD ["flowfuse-device-agent"]