🎨 Allow to set the PUID and PGID using docker (#12596)

* feat: fix docker permission issues * remove VOLUME call on workspace * move responsibility for user and group creation to entrypoint.sh
2024-09-28 05:16:33 +02:00 · 2024-09-28 05:16:33 +02:00 · f0e0b98953
commit f0e0b98953
parent 0292c2cf8f
4 changed files with 137 additions and 32 deletions
--- a/15
+++ b/15
@ -1,4 +1,5 @@
-FROM node:21 as NODE_BUILD
+FROM node:21 AS NODE_BUILD
+
 WORKDIR /go/src/github.com/siyuan-note/siyuan/
 ADD . /go/src/github.com/siyuan-note/siyuan/
 RUN apt-get update && \
@ -17,7 +18,7 @@ RUN apt-get purge -y jq
 RUN apt-get autoremove -y
 RUN rm -rf /var/lib/apt/lists/*

-FROM golang:alpine as GO_BUILD
+FROM golang:alpine AS GO_BUILD
 WORKDIR /go/src/github.com/siyuan-note/siyuan/
 COPY --from=NODE_BUILD /go/src/github.com/siyuan-note/siyuan/ /go/src/github.com/siyuan-note/siyuan/
 ENV GO111MODULE=on
@ -30,6 +31,7 @@ RUN apk add --no-cache gcc musl-dev && \
    mv /go/src/github.com/siyuan-note/siyuan/app/guide/ /opt/siyuan/ && \
    mv /go/src/github.com/siyuan-note/siyuan/app/changelogs/ /opt/siyuan/ && \
    mv /go/src/github.com/siyuan-note/siyuan/kernel/kernel /opt/siyuan/ && \
+    mv /go/src/github.com/siyuan-note/siyuan/kernel/entrypoint.sh /opt/siyuan/entrypoint.sh && \
    find /opt/siyuan/ -name .git | xargs rm -rf

 FROM alpine:latest
@ -37,11 +39,14 @@ LABEL maintainer="Liang Ding<845765@qq.com>"

 WORKDIR /opt/siyuan/
 COPY --from=GO_BUILD /opt/siyuan/ /opt/siyuan/
-RUN addgroup --gid 1000 siyuan && adduser --uid 1000 --ingroup siyuan --disabled-password siyuan && apk add --no-cache ca-certificates tzdata && chown -R siyuan:siyuan /opt/siyuan/
+
+RUN apk add --no-cache ca-certificates tzdata su-exec && \
+    chmod +x /opt/siyuan/entrypoint.sh

 ENV TZ=Asia/Shanghai
+ENV HOME=/home/siyuan
 ENV RUN_IN_CONTAINER=true
 EXPOSE 6806

-USER siyuan
-ENTRYPOINT ["/opt/siyuan/kernel"]
+ENTRYPOINT ["/opt/siyuan/entrypoint.sh"]
+CMD ["/opt/siyuan/kernel"]
--- a/README.md
+++ b/README.md
@ -175,36 +175,53 @@ The overall program is located under `/opt/siyuan/`, which is basically the stru

 #### Entrypoint

-The entry point is set when building the Docker image: `ENTRYPOINT ["/opt/siyuan/kernel" ]`, use `docker run b3log/siyuan` with parameters to start:
+The entry point is set when building the Docker image: `ENTRYPOINT ["/opt/siyuan/entrypoint.sh"]`. This script allows changing the `PUID` and `PGID` of the user that will run inside the container. This is especially relevant to solve permission issues when mounting directories from the host. The `PUID` (User ID) and `PGID` (Group ID) can be passed as environment variables, making it easier to ensure correct permissions when accessing host-mounted directories.

-* `--workspace`: Specifies the workspace folder path, mounted to the container via `-v` on the host
-* `--accessAuthCode`: Specifies the access authorization code
+Use the following parameters when running the container with `docker run b3log/siyuan`:

-More parameters can refer to `--help`. The following is an example of a startup command:
+- `--workspace`: Specifies the workspace folder path, mounted to the container via `-v` on the host
+- `--accessAuthCode`: Specifies the access authorization code

-```
-docker run -d -v workspace_dir_host:workspace_dir_container -p 6806:6806 b3log/siyuan --workspace=workspace_dir_container --accessAuthCode=xxx
+More parameters can be found using `--help`. Here’s an example of a startup command with the new environment variables:
+
+```bash
+docker run -d \
+  -v workspace_dir_host:workspace_dir_container \
+  -p 6806:6806 \
+  -e PUID=1001 -e PGID=1002 \
+  b3log/siyuan \
+  --workspace=workspace_dir_container \
+  --accessAuthCode=xxx
 ```

-* `workspace_dir_host`: The workspace folder path on the host
-* `workspace_dir_container`: The path of the workspace folder in the container, which is the same as specified in `--workspace`
-* `accessAuthCode`: Access authorization code, please **be sure to modify**, otherwise anyone can read and write your data
+- `PUID`: Custom user ID (optional, defaults to `1000` if not provided)
+- `PGID`: Custom group ID (optional, defaults to `1000` if not provided)
+- `workspace_dir_host`: The workspace folder path on the host
+- `workspace_dir_container`: The path of the workspace folder in the container, as specified in `--workspace`
+- `accessAuthCode`: Access authorization code (please **be sure to modify**, otherwise anyone can access your data)

-To simplify, it is recommended to configure the workspace folder path to be consistent on the host and container, such as: `workspace_dir_host` and `workspace_dir_container` are configured as `/siyuan/workspace`, the corresponding startup commands is:
+To simplify things, it is recommended to configure the workspace folder path to be consistent on the host and container, such as having both `workspace_dir_host` and `workspace_dir_container` configured as `/siyuan/workspace`. The corresponding startup command would be:

-```
-docker run -d -v /siyuan/workspace:/siyuan/workspace -p 6806:6806 -u 1000:1000 b3log/siyuan --workspace=/siyuan/workspace/ --accessAuthCode=xxx
+```bash
+docker run -d \
+  -v /siyuan/workspace:/siyuan/workspace \
+  -p 6806:6806 \
+  -e PUID=1001 -e PGID=1002 \
+  b3log/siyuan \
+  --workspace=/siyuan/workspace/ \
+  --accessAuthCode=xxx
 ```

-Alternatively, see below for an example Docker Compose file:
+#### Docker Compose

-```
+For users running Siyuan with Docker Compose, the environment variables `PUID` and `PGID` can be passed to customize the user and group IDs. Here's an example of a Docker Compose configuration:
+
+```yaml
 version: "3.9"
 services:
  main:
    image: b3log/siyuan
    command: ['--workspace=/siyuan/workspace/', '--accessAuthCode=${AuthCode}']
-    user: '1000:1000'
    ports:
      - 6806:6806
    volumes:
@ -212,12 +229,26 @@ services:
    restart: unless-stopped
    environment:
      # A list of time zone identifiers can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-      - TZ=${TimeZone}
+      - TZ=${YOUR_TIME_ZONE}
+      - PUID=${YOUR_USER_PUID}  # Customize user ID
+      - PGID=${YOUR_USER_PGID}  # Customize group ID
 ```

-#### User permissions
+In this setup:
+- `PUID` and `PGID` are set dynamically and passed to the container.
+- If these variables are not provided, the default `1000` will be used.

-In the image, the normal user `siyuan` (uid 1000/gid 1000) created by default is used to start the kernel process. Therefore, when the host creates a workspace folder, please pay attention to setting the user group of the folder:  `chown -R 1000:1000 /siyuan/workspace`. The parameter `-u 1000:1000` is required when starting the container.
+By specifying `PUID` and `PGID` in the environment, you avoid the need to explicitly set the `user` directive (`user: '1000:1000'`) in the compose file. The container will dynamically adjust the user and group based on these environment variables at startup.
+
+#### User Permissions
+
+In the image, the `entrypoint.sh` script ensures the creation of the `siyuan` user and group with the specified `PUID` and `PGID`. Therefore, when the host creates a workspace folder, pay attention to setting the user and group ownership of the folder to match the `PUID` and `PGID` you plan to use. For example:
+
+```bash
+chown -R 1001:1002 /siyuan/workspace
+```
+
+If you use custom `PUID` and `PGID` values, the entrypoint script will ensure that the correct user and group are created inside the container, and ownership of mounted volumes will be adjusted accordingly. There’s no need to manually pass `-u` in `docker run` or `docker-compose` as the environment variables will handle the customization.

 #### Hidden port

@ -229,6 +260,7 @@ Use NGINX reverse proxy to hide port 6806, please note:

 * Be sure to confirm the correctness of the mounted volume, otherwise the data will be lost after the container is deleted
 * Do not use URL rewriting for redirection, otherwise there may be problems with authentication, it is recommended to configure a reverse proxy
+* If you encounter permission issues, verify that the `PUID` and `PGID` environment variables match the ownership of the mounted directories on your host system

 #### Limitations

--- a/README_zh_CN.md
+++ b/README_zh_CN.md
@ -178,36 +178,53 @@

 #### 启动入口

-构建 Docker 镜像时设置了入口：`ENTRYPOINT [ "/opt/siyuan/kernel" ]`，使用 `docker run b3log/siyuan` 并带参即可启动：
+入口点在构建 Docker 镜像时设置： `ENTRYPOINT ["/opt/siyuan/entrypoint.sh"]`。该脚本允许更改将在容器内运行的用户的 `PUID` 和 `PGID`。这对于解决从主机挂载目录时的权限问题尤为重要。`PUID` 和 `PGID` 可以作为环境变量传递，这样在访问主机挂载的目录时就能更容易地确保正确的权限。
+
+使用 `docker run b3log/siyuan` 运行容器时，请使用以下参数：

 * `--workspace`：指定工作空间文件夹路径，在宿主机上通过 `-v` 挂载到容器中
 * `--accessAuthCode`：指定访问授权码

 更多的参数可参考 `--help`。下面是一条启动命令示例：

-```
-docker run -d -v workspace_dir_host:workspace_dir_container -p 6806:6806 b3log/siyuan --workspace=workspace_dir_container --accessAuthCode=xxx
+```bash
+docker run -d \
+  -v workspace_dir_host:workspace_dir_container \
+  -p 6806:6806 \
+  -e PUID=1001 -e PGID=1002 \
+  b3log/siyuan \
+  --workspace=workspace_dir_container \
+  --accessAuthCode=xxx
 ```

+* `PUID`: 自定义用户 ID（可选，如果未提供，默认为 `1000）
+* `PGID`: 自定义组 ID（可选，如果未提供，默认为 `1000）
 * `workspace_dir_host`：宿主机上的工作空间文件夹路径
 * `workspace_dir_container`：容器内工作空间文件夹路径，和后面 `--workspace` 指定成一样的
 * `accessAuthCode`：访问授权码，请**务必修改**，否则任何人都可以读写你的数据

 为了简化，建议将 workspace 文件夹路径在宿主机和容器上配置为一致的，比如将 `workspace_dir_host` 和 `workspace_dir_container` 都配置为 `/siyuan/workspace`，对应的启动命令示例：

-```
-docker run -d -v /siyuan/workspace:/siyuan/workspace -p 6806:6806 -u 1000:1000 b3log/siyuan --workspace=/siyuan/workspace/ --accessAuthCode=xxx
+```bash
+docker run -d \
+  -v /siyuan/workspace:/siyuan/workspace \
+  -p 6806:6806 \
+  -e PUID=1001 -e PGID=1002 \
+  b3log/siyuan \
+  --workspace=/siyuan/workspace/ \
+  --accessAuthCode=xxx
 ```

 使用 Docker Compose 部署请参考下面的示例：

-```
+对于使用 Docker Compose 运行思源的用户，可以通过环境变量 `PUID` 和 `PGID` 来自定义用户和组的 ID。下面是一个 Docker Compose 配置示例：
+
+```yaml
 version: "3.9"
 services:
  main:
    image: b3log/siyuan
    command: ['--workspace=/siyuan/workspace/', '--accessAuthCode=${AuthCode}']
-    user: '1000:1000'
    ports:
      - 6806:6806
    volumes:
@ -215,12 +232,26 @@ services:
    restart: unless-stopped
    environment:
      # A list of time zone identifiers can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-      - TZ=${TimeZone}
+      - TZ=${YOUR_TIME_ZONE}
+      - PUID=${YOUR_USER_PUID}  # 自定义用户 ID
+      - PGID=${YOUR_USER_PGID}  # 自定义组 ID
 ```

+在此设置中：
+- PUID “和 ”PGID "是动态设置并传递给容器的。
+- 如果没有提供这些变量，将使用默认的 `1000`。
+
+在环境中指定 `PUID` 和 `PGID` 后，就无需在组成文件中明确设置 `user` 指令（`user: '1000:1000'`）。容器将在启动时根据这些环境变量动态调整用户和组。
+
 #### 用户权限

-镜像中是使用默认创建的普通用户 `siyuan`（uid 1000/gid 1000）来启动内核进程的，所以在宿主机创建工作空间文件夹时请注意设置该文件夹所属用户组：`chown -R 1000:1000 /siyuan/workspace`，在启动容器时需要带参数 `-u 1000:1000`。
+在图片中，“entrypoint.sh ”脚本确保以指定的 “PUID ”和 “PGID ”创建 “siyuan ”用户和组。因此，当主机创建工作区文件夹时，请注意设置文件夹的用户和组所有权，使其与计划使用的 `PUID` 和 `PGID` 匹配。例如
+
+```bash
+chown -R 1001:1002 /siyuan/workspace
+```
+
+如果使用自定义的 `PUID` 和 `PGID` 值，入口点脚本将确保在容器内创建正确的用户和组，并相应调整挂载卷的所有权。无需在 `docker run` 或 `docker-compose` 中手动传递 `-u`，因为环境变量会处理自定义。

 #### 隐藏端口

--- a/kernel/entrypoint.sh
+++ b/kernel/entrypoint.sh
@ -0,0 +1,37 @@
+#!/bin/sh
+set -e
+
+# Default values
+PUID=${PUID:-1000}
+PGID=${PGID:-1000}
+USER_NAME=${USER_NAME:-siyuan}
+GROUP_NAME=${GROUP_NAME:-siyuan}
+
+# Get or create group
+group_name="${GROUP_NAME}"
+if getent group "${PGID}" > /dev/null 2>&1; then
+    group_name=$(getent group "${PGID}" | cut -d: -f1)
+    echo "Using existing group: ${group_name} (${PGID})"
+else
+    echo "Creating group ${group_name} (${PGID})"
+    addgroup --gid "${PGID}" "${group_name}"
+fi
+
+# Get or create user
+user_name="${USER_NAME}"
+if id -u "${PUID}" > /dev/null 2>&1; then
+    user_name=$(getent passwd "${PUID}" | cut -d: -f1)
+    echo "Using existing user ${user_name} (PUID: ${PUID}, PGID: ${PGID})"
+else
+    echo "Creating user ${user_name} (PUID: ${PUID}, PGID: ${PGID})"
+    adduser --uid "${PUID}" --ingroup "${group_name}" --disabled-password --gecos "" "${user_name}"
+fi
+
+# Change ownership of relevant directories
+echo "Adjusting ownership of /opt/siyuan and /home/siyuan/"
+chown -R "${PUID}:${PGID}" /opt/siyuan
+chown -R "${PUID}:${PGID}" /home/siyuan/
+
+# Switch to the newly created user and start the main process
+echo "Starting Siyuan with UID:${PUID} and GID:${PGID}"
+exec su-exec "${PUID}:${PGID}" /opt/siyuan/kernel "$@"