Merge pull request #167 from thin-edge/docs-rootless-setup-options

docs: add instructions for setting up podman in rootless mode

Author: reubenmiller

README.md

@@ -79,6 +79,14 @@ If your device is not finding the correct socket path for your container engine,
 host = "unix:///run/podman/podman.sock"
 ```
 
+### Rootless container engines
+
+Running a container engine in rootless mode requires some additional setup which can't be provided in the default package, however the following pages provide some hints on how to get it setup.
+
+* [podman (rootless)](./docs/PODMAN_ROOTLESS.md)
+
+If you run into any problems with the rootless setup, then please consult the relevant container engine's documentation for more up-to-date instructions (and feel free to submit a PR in this repository).
+
 ### Install/remove single containers
 
 Containers can be installed and removed via the Cumulocity Software Management interface in the Device Management Application.

docs/PODMAN_ROOTLESS.md

@@ -0,0 +1,57 @@
+# Using tedge-container-plugin with podman rootless
+
+The following page includes some hints on how to setup podman in rootless mode so that the tedge user can run commands.
+
+If you run into any errors please consult the official container engine's documentation.
+
+## Alpine Linux (with OpenRC)
+
+1. Create a home folder for the tedge user (required by podman)
+
+    ```sh
+    sudo apk --no-cache add shadow
+    sudo mkdir -p /home/tedge/.config/containers/
+    sudo chown -R tedge:tedge /home/tedge
+    sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 tedge
+    ```
+
+    If you need/want to avoid installing the `shadow` package (which provides the `usermod` command) then you will have to manually modify the `/etc/subuid` and `/etc/subgid` files. below shows an example of how to do this.
+
+    ```sh
+    echo tedge:100000:165535 | sudo tee -a /etc/subuid
+    echo tedge:100000:165535 | sudo tee -a /etc/subgid
+    ```
+
+    **Note:** Technically it would be feasible to edit the default storage path in the container.conf file, however that change might be more invasive for other users who wish to run their own podman rootless containers.
+
+2. Edit the podman OpenRC service to run the api endpoint (socket) under a non-root user
+
+    ```sh
+    sudo sed -i 's/.*podman_user=.*/podman_user="tedge"/g' /etc/conf.d/podman
+    ```
+
+3. Restart the podman api service
+
+    ```sh
+    sudo tedgectl restart podman
+    ```
+
+    **Note:** You can also run the openrc specific commands, `tedgectl` just makes it easier and is service manager agnostic.
+
+4. Edit the tedge-container service to run using the tedge user (instead of root)
+
+    **OpenRC**
+
+    Change the `command_user` to use `tedge`
+
+    ```sh
+    sudo sed -i 's/.*command_user=.*/command_user="tedge"/g' /etc/conf.d/tedge-container-plugin
+    ```
+
+5. Restart the tedge-container-plugin service
+
+    ```sh
+    sudo tedgectl restart tedge-container-plugin
+    ```
+
+    **Note:** You can also run the openrc specific commands, `tedgectl` just makes it easier and is service manager agnostic.

test-images/alpine-openrc-podman-cli-rootless/Dockerfile

@@ -0,0 +1,67 @@
+FROM docker.io/alpine:3.22
+ARG TARGETPLATFORM
+
+RUN apk add --no-cache \
+        openrc \
+        mdevd-openrc \
+        wget \
+        curl \
+        bash \
+        sudo \
+        jq \
+        dasel \
+        shadow \
+        podman \
+        podman-compose \
+        # Required when running inside docker
+        # see https://github.com/containers/buildah/issues/3666
+        fuse-overlayfs \
+        # Add packages which are required for rootless
+        shadow-uidmap \
+        iproute2 \
+        ip6tables \
+    && wget -O - thin-edge.io/install.sh | sh -s \
+    && apk add \
+        tedge-apk-plugin \
+        tedge-command-plugin
+
+ADD https://raw.githubusercontent.com/thin-edge/tedge-demo-container/refs/heads/main/images/common/bootstrap.sh /usr/bin/
+RUN chmod 755 /usr/bin/bootstrap.sh
+
+RUN sed -i '/getty/d' /etc/inittab \
+    && sed -i 's/#mount_program/mount_program/' /etc/containers/storage.conf
+
+COPY dist/*.apk /tmp/
+RUN case ${TARGETPLATFORM} in \
+        "linux/386")  PKG_ARCH=linux_386  ;; \
+        "linux/amd64")  PKG_ARCH=linux_amd64  ;; \
+        "linux/arm64")  PKG_ARCH=linux_arm64  ;; \
+        "linux/arm/v6")  PKG_ARCH=linux_armv6  ;; \
+        "linux/arm/v7")  PKG_ARCH=linux_armv7  ;; \
+        *) echo "Unsupported target platform: TARGETPLATFORM=$TARGETPLATFORM"; exit 1 ;; \
+    esac \
+    && apk add --allow-untrusted /tmp/*${PKG_ARCH}*.apk \
+    && mkdir -p /opt/packages \
+    && cp /tmp/*${PKG_ARCH}*.apk /opt/packages/ \
+    && rm -f /tmp/*.apk
+
+RUN echo "tedge  ALL = (ALL) NOPASSWD: /usr/bin/tedge-container" | tee /etc/sudoers.d/tedge-containers \
+    && mkdir -p /etc/tedge-container-plugin \
+    && echo "CONTAINER_METRICS_INTERVAL=60s" | tee -a /etc/tedge-container-plugin/env \
+    && dasel put -r toml -t string -v '60s' 'metrics.interval' --indent 0 < /etc/tedge/plugins/tedge-container-plugin.toml > /etc/tedge/plugins/tedge-container-plugin.toml.tmp \
+    && mv /etc/tedge/plugins/tedge-container-plugin.toml.tmp /etc/tedge/plugins/tedge-container-plugin.toml
+
+# Setup podman rootless for the tedge user
+RUN mkdir -p /home/tedge/.config/containers/ \
+    && chown -R tedge:tedge /home/tedge \
+    && usermod --add-subuids 100000-165535 --add-subgids 100000-165535 tedge \
+    && sed -i 's/.*podman_user=.*/podman_user="tedge"/g' /etc/conf.d/podman \
+    && sed -i 's/.*command_user=.*/command_user="tedge"/g' /etc/conf.d/tedge-container-plugin \
+    # Workaround: disable modprobe checks due to an issue with /lib/modules not being present
+    # possibly due to running podman within docker?
+    && sed -i 's/modprob/#modprobe/g' /etc/init.d/podman
+
+# Default services
+RUN rc-update add podman
+
+CMD ["/sbin/init"]