Development setup script and analogous Dockerfile (#36)

greenc-FNAL · google-labs-jules[bot] · web-flow · commit 36d35fec6bbd · 2025-12-12T15:09:08.000-06:00
* feat: Create script to set up cetmodules development environment

This script automates the setup of a development environment for
cetmodules on Ubuntu and AlmaLinux. It performs the following steps:

- Detects the operating system (Ubuntu or AlmaLinux) and uses the
  appropriate package manager.
- Installs system dependencies such as git, doxygen, graphviz, and
  build tools.
- Sets up a Python virtual environment and installs CMake, Sphinx, and
  other required Python packages.
- Clones the Catch2 repository, builds it, and installs it.
- Clones the cetmodules repository, configures the build with
  documentation enabled, builds the project, and runs the tests.
- Builds the cetmodules documentation.

* Prelims for container definition

* feat(dev): Add Docker-based development environment

Adds a Dockerfile and instructions for building and running a containerized development environment for cetmodules.

The new configuration, located in `dev/container/`, provides a consistent and reproducible environment with all necessary dependencies installed. It is configured to support an out-of-source build workflow and includes a non-root user to avoid file ownership issues when mounting the source directory.

A `README.md` is included with detailed instructions for building the image and running the container.

* fix(dev): Add --break-system-packages to Dockerfile

This commit resolves a build failure in the development container.

Recent versions of Python in Ubuntu/Debian images prevent `pip` from installing packages globally to avoid conflicts with the system's package manager. This change adds the `--break-system-packages` flag to the `pip3 install` command in the `Dockerfile` to override this protection, which is a safe and necessary step within a self-contained container.

* fix(dev): Avoid UID conflict in Dockerfile

This commit resolves a build failure in the development container caused by a UID conflict.

The `useradd` command failed because UID 1000 was already in use in the base Ubuntu image. This change modifies the UID for the `developer` user to 5000 to avoid this conflict.

* Dockerfile tweaks and documentation

* Add missing system requirements

* feat(devcontainer): Improve UID/GID handling and volume mounts

This commit introduces a more robust and user-friendly development container setup.

It replaces the previous mechanism of relying on the `--user` flag with an entrypoint script that dynamically adjusts the in-container `developer` user's UID and GID to match the host user's. This is a best-practice pattern for pre-built images that solves file ownership issues on mounted volumes.

The key changes include:
- An `entrypoint.sh` script to manage user mapping at runtime.
- Use of `gosu` for secure privilege dropping.
- An updated `Dockerfile` to incorporate the entrypoint.
- Revised `README.md` with clear instructions for running the container with both `/source` and `/build` volumes mounted.

fix(devcontainer): Use non-reserved variable names in entrypoint

This commit fixes a bug in the `entrypoint.sh` script that caused the container to fail on startup.

The script was using the reserved bash variable `UID`, which is readonly. This resulted in an error when the script attempted to assign a new value to it.

The fix renames the conflicting variables from `UID` and `GID` to `TARGET_UID` and `TARGET_GID` respectively, resolving the runtime error.

fix(devcontainer): Prevent entrypoint from changing host source permissions

This commit corrects a critical bug in the `entrypoint.sh` script that caused it to recursively change the ownership of the mounted `/source` directory, altering the user's project files on the host.

The `chown -R` command in the script is now restricted to only the `/build` and `/home/developer` directories. This ensures that the container has correct write permissions for build artifacts and its home directory, while leaving the ownership of the user's source code untouched.

This change makes the development container safe to use and prevents it from having unintended and destructive side effects on the host system.

revert(devcontainer): Remove entrypoint and use --user for UID/GID

This commit reverts the entrypoint-based approach and returns to a simpler, more compatible method for handling user permissions that works correctly with both Docker and Podman.

The previous entrypoint-based solution, while a common pattern for Docker, is incompatible with Podman's user namespace mapping (`--userns=keep-id`). This incompatibility led to incorrect file ownership on the host's build directory.

The corrected approach is to:
1.  Remove the `entrypoint.sh` script entirely.
2.  Simplify the `Dockerfile` by removing the `gosu` dependency and entrypoint logic.
3.  Make the `/source` and `/build` directories inside the container world-writable (`chmod 777`).
4.  Use the standard `--user "$(id -u):$(id -g)"` flag when running the container.

This method allows the user specified on the command line to write to the mounted volumes without permission errors and ensures that the created files have the correct ownership on the host, which is the desired behavior for both Podman and Docker. The `README.md` has been updated to reflect this final, correct usage.

fix(devcontainer): Remove developer user for Podman compatibility

This commit provides the final, correct implementation for the development container, ensuring compatibility with Podman's user namespace features.

The previous approach of creating a `developer` user inside the `Dockerfile` conflicted with Podman's user mapping when the `--user` flag was used. This resulted in the user inside the container not having the expected ownership of the mounted `/build` volume.

The solution is to remove the `developer` user entirely from the `Dockerfile`. The image is now prepared with world-writable `/source` and `/build` directories, making it a generic environment ready to be used by any user ID passed via the `--user` flag.

This is the simplest and most robust solution, guaranteeing correct file ownership on mounted volumes for both Docker and Podman users.

docs(devcontainer): Add correct run instructions for Docker and Podman

This commit updates the `README.md` to provide clear and distinct instructions for running the development container with Docker and rootless Podman.

The previous instructions were a source of confusion and permission errors due to fundamental differences in how Docker and rootless Podman handle user namespaces.

The new documentation clarifies that:
- Docker users should continue to use `--user "$(id -u):$(id -g)"` to ensure correct file ownership.
- Rootless Podman users should run as the default `root` user inside the container. Podman's user namespace will safely map this to their user on the host, ensuring correct file ownership on mounted volumes.

This change, combined with the simplified `Dockerfile`, provides a robust and easy-to-use solution for all users.

---------

Co-authored-by: google-labs-jules[bot] &lt;161369871+google-labs-jules[bot]@users.noreply.github.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+/build
+/build.log
+/venv
diff --git a/dev/container/.dummy b/dev/container/.dummy
diff --git a/dev/container/Dockerfile b/dev/container/Dockerfile
@@ -0,0 +1,53 @@
+# Dockerfile for building Cetmodules development image.
+
+# Podman instructions for building and uploading tagged images:
+#   $ DATE="$(date +"%Y-%m-%d")"
+#   $ podman build --tag cetmodules-dev:$DATE .
+#   $ podman login ghcr.io --username <username> -p $(gh auth token)
+#   $ podman push cetmodules-dev:$DATE ghcr.io/fnalssi/cetmodules-dev:$DATE
+# ... and optionally push with destination tag "latest"
+
+# Base image
+FROM ubuntu:latest
+
+# Set non-interactive frontend to avoid prompts
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    doxygen \
+    graphviz \
+    m4 \
+    ninja-build \
+    python3 \
+    python3-pip \
+    sudo && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install Python packages
+RUN pip3 install --no-cache-dir --break-system-packages \
+    cmake \
+    sphinx \
+    sphinxcontrib-moderncmakedomain \
+    sphinx-design \
+    sphinx-toolbox \
+    sphinxcontrib-jquery
+
+# Install Catch2
+RUN git clone https://github.com/catchorg/Catch2.git /tmp/Catch2 && \
+    cmake -S /tmp/Catch2 -B /tmp/Catch2/build -DBUILD_TESTING=OFF && \
+    cmake --build /tmp/Catch2/build --target install && \
+    rm -rf /tmp/Catch2
+
+# Create source and build directories and make them world-writable
+RUN mkdir /source /build && \
+    chmod 777 /source /build
+
+# Set working directory
+WORKDIR /build
+
+# Set default command
+CMD ["/bin/bash"]
diff --git a/dev/container/README.md b/dev/container/README.md
@@ -0,0 +1,57 @@
+# Cetmodules Development Container
+
+This directory contains a `Dockerfile` to create a containerized development environment for `cetmodules`.
+
+## Building the Image
+
+To build the image, run the following command from the root of the repository:
+
+```bash
+# For Docker or Podman
+docker build -t cetmodules-dev dev/container
+```
+
+## Running the Container
+
+The command to run the container differs between Docker and Podman due to differences in how they handle user namespaces.
+
+First, create a local `build` directory if it does not already exist:
+
+```bash
+mkdir -p build
+```
+
+### For Docker Users
+
+Docker users should map their host user ID directly to the container to ensure correct file ownership on mounted volumes.
+
+```bash
+docker run -it --rm \
+  --user "$(id -u):$(id -g)" \
+  -v "$(pwd):/source" \
+  -v "$(pwd)/build:/build" \
+  cetmodules-dev
+```
+
+### For Podman Users (Rootless)
+
+Rootless Podman uses user namespaces to map your host user to the `root` user (UID 0) inside the container. To ensure you have permission to write to mounted volumes, you should run as `root` inside the container. Any files created in the mounted volumes will be correctly owned by your user on the host.
+
+```bash
+podman run -it --rm \
+  -v "$(pwd):/source" \
+  -v "$(pwd)/build:/build" \
+  cetmodules-dev
+```
+*(Note: Running as `root` is the intended usage for rootless Podman and is safe because you are in an unprivileged user namespace.)*
+
+
+### Usage
+
+Once inside the container, you can perform an out-of-source build like this:
+
+```bash
+cmake -S /source -B . -DBUILD_DOCS=ON
+cmake --build .
+ctest
+```
diff --git a/dev/setup_cetmodules_dev.sh b/dev/setup_cetmodules_dev.sh
@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# Exit immediately if a command exits with a non-zero status.
+set -e
+
+# --- OS Detection ---
+if [ -f /etc/os-release ]; then
+    . /etc/os-release
+    if [[ "$ID" == "ubuntu" ]]; then
+        PACKAGE_MANAGER="apt-get"
+        BUILD_DEPS="build-essential"
+    elif [[ "$ID" == "almalinux" ]]; then
+        PACKAGE_MANAGER="dnf"
+        BUILD_DEPS="gcc-c++"
+    else
+        echo "Unsupported operating system: $ID"
+        exit 1
+    fi
+else
+    echo "/etc/os-release not found. Cannot determine operating system."
+    exit 1
+fi
+
+# --- System Dependency Installation ---
+echo "Updating package lists..."
+sudo $PACKAGE_MANAGER update -y
+
+echo "Installing system dependencies..."
+sudo $PACKAGE_MANAGER install -y git doxygen graphviz python3-venv $BUILD_DEPS
+
+# --- Python Environment Setup ---
+echo "Setting up Python virtual environment..."
+python3 -m venv venv
+source venv/bin/activate
+
+echo "Installing Python packages (CMake, Sphinx, etc.)..."
+pip install cmake sphinx sphinxcontrib-moderncmakedomain sphinx-design sphinx-toolbox sphinxcontrib-jquery
+
+# --- Catch2 Installation ---
+echo "Cloning and installing Catch2..."
+git clone https://github.com/catchorg/Catch2.git
+cd Catch2
+cmake -S . -B build -DBUILD_TESTING=OFF
+sudo cmake --build build --target install
+cd ..
+rm -rf Catch2
+
+# --- cetmodules Build and Test ---
+echo "Cloning, building, and testing cetmodules..."
+git clone https://github.com/FNALssi/cetmodules.git
+cd cetmodules
+cmake -S . -B build -DBUILD_DOCS=ON
+cmake --build build
+ctest --test-dir build
+
+# --- Documentation Build ---
+echo "Building cetmodules documentation..."
+cmake --build build --target doc-cetmodules-reference
+cd ..
+
+# --- Completion ---
+echo ""
+echo "----------------------------------------------------"
+echo "Development environment setup for cetmodules is complete!"
+echo "To activate the Python virtual environment, run:"
+echo "source venv/bin/activate"
+echo "----------------------------------------------------"
