fix: simplify Docker setup

Especially the user and group IDs can simply be passed into the Docker
container without the need of an entrypoint script.

Author: 6arms1leg

Dockerfile

@@ -1,37 +1,63 @@
 # Usage:
 #
-# /strictdoc$ docker build . -t strictdoc:latest
-# /strictdoc$ docker run --name strictdoc --rm -v "$(pwd):/data" -i -t strictdoc:latest
-# bash-5.1# strictdoc export .
-# bash-5.1# exit
-# strictdoc$ firefox docs/output/html/index.html
+# /strictdoc$ docker build \
+#                 ./ \
+#                 --build-arg STRICTDOC_SOURCE=pypi \
+#                 --tag strictdoc:latest
+# /strictdoc$ docker run \
+#                 --rm \
+#                 --volume="$(pwd):/data/" \
+#                 --user=$(id -u):$(id -g) \
+#                 --userns=host \
+#                 --network=host \
+#                 --hostname="strictdoc" \
+#                 --name="strictdoc" \
+#                 --init \
+#                 --tty \
+#                 strictdoc:latest \
+#                     export ./
+# /strictdoc$ firefox ./output/html/index.html
 
 FROM ubuntu:24.04
 
+# Workaround: Newly introduced `ubuntu` user in ubuntu:24.04 causes UID/GID
+# mapping issues when adding custom user.
+RUN touch /var/mail/ubuntu && \
+    chown ubuntu /var/mail/ubuntu && \
+    userdel --remove ubuntu
+
+# Main "payload" software
+ARG PAYLOAD=strictdoc
+
+# Docker image labels
+LABEL maintainer="StrictDoc Project"
+LABEL name="${PAYLOAD}"
+LABEL description="Software for technical documentation and requirements management."
+
 # Install dependencies
-RUN apt-get update && apt-get install -y \
-    curl \
-    git \
-    gosu \
-    python3 \
-    python3-pip \
-    python3-venv \
-    sudo \
-    vim \
-    wget \
-    && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install --assume-yes --no-install-recommends \
+        curl \
+        git \
+        python3 \
+        python3-pip \
+        python3-venv \
+        vim \
+        wget \
+    && \
+    rm --recursive --force /var/lib/apt/lists/*
 
 # Download and install Google Chrome
-RUN wget -q -O google-chrome.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb \
-    && apt-get update \
-    && apt-get install -y ./google-chrome.deb \
-    && rm google-chrome.deb
+RUN wget --quiet --output-document=google-chrome.deb \
+        https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && \
+    apt-get update && \
+    apt-get install --assume-yes --no-install-recommends ./google-chrome.deb && \
+    rm --recursive --force /var/lib/apt/lists/* && \
+    rm --force google-chrome.deb
 
-# Create a virtual environment in the user's home directory.
-RUN python3 -m venv /opt/venv
-
-# Ensure the virtual environment is used by modifying the PATH.
-ENV PATH="/opt/venv/bin:$PATH"
+# Create a virtual environment and ensure it is used by modifying the PATH.
+ENV VIRTUAL_ENV=/opt/venv
+RUN python3 -m venv ${VIRTUAL_ENV}
+ENV PATH="${VIRTUAL_ENV}/bin:$PATH"
 
 # Install StrictDoc. Set default StrictDoc installation from PyPI but allow
 # overriding it with an environment variable.
@@ -44,17 +70,16 @@ RUN if [ "$STRICTDOC_SOURCE" = "pypi" ]; then \
     else \
       pip install --no-cache-dir --upgrade pip && \
       pip install --no-cache-dir git+https://github.com/strictdoc-project/strictdoc.git@${STRICTDOC_SOURCE}; \
-    fi; \
-    chmod -R 777 /opt/venv;
-
-# Remove the default 'ubuntu' user.
-RUN userdel -r ubuntu 2>/dev/null || true
+    fi;
 
-# Allow updating the UID/GID dynamically at runtime
-COPY entrypoint.sh /entrypoint.sh
-RUN chmod +x /entrypoint.sh
+# Switch to non-root user
+RUN groupadd ${PAYLOAD} && \
+    useradd --no-log-init --gid ${PAYLOAD} ${PAYLOAD}
+USER ${PAYLOAD}
 
-# Set the working directory to the user's home directory.
-WORKDIR /data
+# Set up working directory.
+WORKDIR /data/
 
-ENTRYPOINT ["/entrypoint.sh"]
+# Execute StrictDoc by default
+ENTRYPOINT ["strictdoc"]
+CMD ["--help"]

docs/strictdoc_01_user_guide.sdoc

@@ -130,11 +130,11 @@ STATEMENT: >>>
     TITLE: Requirements management
     STATEMENT: StrictDoc shall enable requirements management.
 
-Create a file called ``hello_world.sdoc`` somewhere on your file system and copy the above "Hello World" example text to it. **The file must end with a newline character**.
+Create a file called ``hello.sdoc`` somewhere on your file system and copy the above "Hello World" example text to it. **The file must end with a newline character**.
 
 Open a command-line terminal program supported on your system.
 
-Once you have ``strictdoc`` installed (see [LINK: SDOC_UG_GETTING_STARTED] below), switch to the directory with the ``hello_world.sdoc`` file. For example, assuming that the file is now in the ``workspace/hello_world`` directory in your user folder:
+Once you have ``strictdoc`` installed (see [LINK: SDOC_UG_GETTING_STARTED] below), switch to the directory with the ``hello.sdoc`` file. For example, assuming that the file is now in the ``workspace/hello_world`` directory in your user folder:
 
 .. code-block:: text
 
@@ -295,25 +295,48 @@ To build the image:
 
 .. code-block:: text
 
-    docker build . \
+    docker build \
+        ./ \
         --build-arg STRICTDOC_SOURCE=pypi \
-        -t strictdoc:latest
+        --tag strictdoc:latest
 
 The ``STRICTDOC_SOURCE`` argument is optional (default value is ``pypi``) and can be used to specify which Git revision the container shall check out when installing StrictDoc with ``pip install``. Possible values: a branch name, e.g., ``main``, or a commit hash.
 
-To run the container:
+To run the container and execute StrictDoc directly:
 
 .. code-block:: text
 
     docker run \
-        --name strictdoc \
         --rm \
-        -e HOST_UID=$(id -u) \
-        -e HOST_GID=$(id -g) \
-        -v "$(pwd):/data" \
-        -i -t \
+        --volume="$(pwd):/data/" \
+        --user=$(id -u):$(id -g) \
+        --userns=host \
+        --network=host \
+        --hostname="strictdoc" \
+        --name="strictdoc" \
+        --init \
+        --tty \
         strictdoc:latest \
-        /bin/bash -c "strictdoc export --formats=html"
+            export --formats=html ./
+
+To run an interactive container with a shell:
+
+.. code-block:: text
+
+    docker run \
+        --rm \
+        --volume="$(pwd):/data/" \
+        --user=$(id -u):$(id -g) \
+        --userns=host \
+        --network=host \
+        --hostname="strictdoc" \
+        --name="strictdoc" \
+        --init \
+        --interactive \
+        --tty \
+        --entrypoint="" \
+        strictdoc:latest \
+            bash
 
 .. list-table:: ``docker run`` options breakdown
    :widths: 40 60
@@ -325,21 +348,27 @@ To run the container:
    * - ``--rm``
      - Remove container when it is exited.
 
-   * - ``HOST_UID`` and ``HOST_GID``
-     - These environment variables are used to tell the container that it should create a ``strictdoc`` user that has these values. This enables the content generated by the container to be visible outside the container under the permissions of the host user.
+   * - ``--volume="<folder on host>:/data/"``
+     - Normally the folder on the host should be the folder with the StrictDoc documentation. The ``/data/`` folder must always be specified without change because that's where the Docker container is designed to operate.
+
+   * - ``--user=$(id -u):$(id -g)``
+     - Map the host user's user and group ID to the container user's IDs. This enables the content generated by the container to be visible outside the container under the permissions of the host user.
+
+   * - ``--network=host``
+     - Map the host network into the container.
 
-   * - ``-v "<folder on host>:/data"``
-     - Normally the folder on the host should be the folder with the StrictDoc documentation. The ``/data`` folder must always be specified without change because that's where the Docker container is designed to operate.
+   * - ``--init``
+     - Forward signals.
 
-   * - ``/bin/bash -c "..."``
-     - This command shall typically be ``strictdoc export`` but it can also be skipped in which case the ``docker run`` will enter the container with SSH.
+   * - ``--entrypoint=""``
+     - Override entrypoint as empty to run a different command, e.g. Bash. (The default entrypoint is ``strictdoc``.)
 
-If entering the container manually, the ``strictdoc`` command can be run as follows:
+If running an interactive container with a shell, the ``strictdoc`` command can be executed as follows:
 
 .. code-block:: text
 
-    bash-5.1# strictdoc export .
-    bash-5.1# exit
+    ubuntu@strictdoc:/data$ strictdoc export .
+    ubuntu@strictdoc:/data$ exit
 
 The documentation shall be generated to ``./output/html`` which is accessible both on the host and inside the container.
 <<<

entrypoint.sh

@@ -969,33 +969,37 @@ def build_docker(
     run_invoke(
         context,
         f"""
-        docker build .
+        docker build
+            ./
             --build-arg STRICTDOC_SOURCE={source}
-            -t {image}
+            --tag {image}
             {no_cache_argument}
         """,
+        pty=True,
     )
 
 
 @task(aliases=["rd"])
 def run_docker(
     context, image: str = "strictdoc:latest", command: Optional[str] = None
 ):
-    command_argument = (
-        f'/bin/bash -c "{command}"' if command is not None else ""
-    )
+    command_argument = f"{command}" if command is not None else ""
 
     run_invoke(
         context,
         f"""
         docker run
-            --name strictdoc
             --rm
-            -it
-            -e HOST_UID=$(id -u) -e HOST_GID=$(id -g)
-            -v "$(pwd):/data"
+            --volume="$(pwd):/data/"
+            --user=$(id -u):$(id -g)
+            --userns=host
+            --network=host
+            --hostname="strictdoc"
+            --name="strictdoc"
+            --init
+            --tty
             {image}
-            {command_argument}
+                {command_argument}
         """,
         pty=True,
     )
@@ -1012,7 +1016,7 @@ def test_docker(context, image: str = "strictdoc:latest"):
     run_docker(
         context,
         image=image,
-        command="strictdoc export --formats=html,html2pdf .",
+        command="export --formats=html,html2pdf ./",
     )
 
     def check_file_owner(filepath):