diff --git a/doc/changelog.d/1563.fixed.md b/doc/changelog.d/1563.fixed.md new file mode 100644 index 0000000000..a780004a47 --- /dev/null +++ b/doc/changelog.d/1563.fixed.md @@ -0,0 +1 @@ +Add user to docker files diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index 8270b18a8e..f785b64f85 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -121,6 +121,33 @@ Verify your connection with this code: Additional considerations ------------------------- +.. _docker_container_user: + +Container user +~~~~~~~~~~~~~~~ + +The Mechanical Docker image runs as a non-root user named ``mechanical`` (UID ``1000``) +by default. That matches common container security guidance: the main process does not +run as ``root``. + +Implications: + +- **Interactive shell:** ``docker run -it --entrypoint=/bin/bash ...`` starts ``bash`` as + ``mechanical``, not as ``root``. +- **System packages (``apt``):** Installing packages with ``apt-get`` requires root. Use a + root shell for that session, for example: + + .. code:: bash + + docker run -it --user root --entrypoint=/bin/bash mechanical:26.1 + # apt-get update && apt-get install -y + + If a container is already running, you can run ``docker exec -it -u root bash``. + +- **User-level tools:** Installations under your home directory (for example ``pip install --user``, + a Python virtual environment, or the `uv `_ installer targeting + ``$HOME``) typically work as ``mechanical`` without ``root``. + You can provide additional command line parameters to Mechanical by appending them to the Docker command. For example, this code shows how you pass feature flags: @@ -139,14 +166,16 @@ For additional command line arguments, see the `Scripting in Mechanical Guide`_ Ansys Help. -For PyMechanical embedding, you can directly enter the container using ``--entrypoint=/bin/bash`` -and then install Python packages as needed. +For PyMechanical embedding, you can enter the container with ``--entrypoint=/bin/bash`` and +install Python packages (for example into a virtual environment or user site) as the default +``mechanical`` user. If you need ``apt-get`` to add system packages, start the container with +``--user root`` or use ``docker exec -u root`` as described in :ref:`docker_container_user`. .. code:: bash docker run -it -e ANSYSLMD_LICENSE_FILE=$LICENSE_SERVER --entrypoint=/bin/bash mechanical:26.1 - # Once inside the container, you can install Python and packages as needed, then create an embedded app. + # Inside the container: install Python tooling (venv, pip, uv, etc.), then create an embedded app. .. note:: diff --git a/docker/242/Dockerfile b/docker/242/Dockerfile index 690f9177d7..536c6256ef 100644 --- a/docker/242/Dockerfile +++ b/docker/242/Dockerfile @@ -68,6 +68,10 @@ WORKDIR /install/ COPY . . +RUN useradd -m -u 1000 mechanical \ + && chown -R mechanical:mechanical /install +USER mechanical + # License server # (Optional) # ENV LICENSE_SERVER=111.222.333.444 diff --git a/docker/251/Dockerfile b/docker/251/Dockerfile index 1c0d23ff34..3182ee9fb8 100644 --- a/docker/251/Dockerfile +++ b/docker/251/Dockerfile @@ -75,6 +75,10 @@ WORKDIR /install/ COPY . . +RUN useradd -m -u 1000 mechanical \ + && chown -R mechanical:mechanical /install +USER mechanical + # License server # (Optional) # ENV LICENSE_SERVER=111.222.333.444 diff --git a/docker/252/Dockerfile b/docker/252/Dockerfile index ec633cd40d..70159b9b9d 100644 --- a/docker/252/Dockerfile +++ b/docker/252/Dockerfile @@ -75,6 +75,10 @@ WORKDIR /install/ COPY . . +RUN useradd -m -u 1000 mechanical \ + && chown -R mechanical:mechanical /install +USER mechanical + # License server # (Optional) # ENV LICENSE_SERVER=111.222.333.444 diff --git a/docker/261/Dockerfile b/docker/261/Dockerfile index 4249ad6b3f..23e2c56095 100644 --- a/docker/261/Dockerfile +++ b/docker/261/Dockerfile @@ -72,6 +72,10 @@ WORKDIR /install/ COPY . . +RUN useradd -m -u 1000 mechanical \ + && chown -R mechanical:mechanical /install +USER mechanical + # License server # (Optional) # ENV LICENSE_SERVER=111.222.333.444