feat: replace container base images with pixi-managed environments

Move container builds from the multi-repo base image approach (micromamba
+ conda environment.yml + pip install --no-deps) to self-contained
multi-stage Dockerfiles using pixi environments from the committed lock
file. This ensures reproducible builds with exact version parity between
development and production.

Author: chrisburr

.github/workflows/deployment.yml

@@ -97,7 +97,7 @@ jobs:
 
   docker:
     needs: deploy-pypi
-    timeout-minutes:  30
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -112,58 +112,42 @@ jobs:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Download diracx wheels
-        uses: actions/download-artifact@v7
-        with:
-            name: diracx-whl
-      - name: "Find wheels"
-        id: find_wheel
-        run: |
-          # We need to copy them there to be able to access them in the RUN --mount
-          cp diracx*.whl containers/client/
-          cp diracx*.whl containers/services/
-          for wheel_fn in *.whl; do
-            pkg_name=$(basename "${wheel_fn}" | cut -d '-' -f 1)
-            echo "${pkg_name}-wheel-name=$(ls "${pkg_name}"-*.whl)" >> $GITHUB_OUTPUT
-          done
 
-      - name: Build and push client (release)
+      - name: Build and push services (release)
         uses: docker/build-push-action@v6
         if: ${{ needs.deploy-pypi.outputs.create-release == 'true' }}
         with:
-          context: containers/client/
-          push: ${{ needs.deploy-pypi.outputs.create-release == 'true' }}
-          tags: "ghcr.io/diracgrid/diracx/client:${{ needs.deploy-pypi.outputs.new-version }}"
+          context: .
+          file: containers/services/Dockerfile
+          push: true
+          tags: "ghcr.io/diracgrid/diracx/services:${{ needs.deploy-pypi.outputs.new-version }}"
           platforms: linux/amd64,linux/arm64
-          build-args: EXTRA_PACKAGES_TO_INSTALL=DIRACCommon~=9.0.0
-      - name: Build and push services (release)
+      - name: Build and push client (release)
         uses: docker/build-push-action@v6
         if: ${{ needs.deploy-pypi.outputs.create-release == 'true' }}
         with:
-          context: containers/services/
-          push: ${{ needs.deploy-pypi.outputs.create-release == 'true' }}
-          tags: "ghcr.io/diracgrid/diracx/services:${{ needs.deploy-pypi.outputs.new-version }}"
+          context: .
+          file: containers/client/Dockerfile
+          push: true
+          tags: "ghcr.io/diracgrid/diracx/client:${{ needs.deploy-pypi.outputs.new-version }}"
           platforms: linux/amd64,linux/arm64
-          build-args: EXTRA_PACKAGES_TO_INSTALL=DIRACCommon~=9.0.0
 
-      - name: Build and push client (dev)
+      - name: Build and push services (dev)
         uses: docker/build-push-action@v6
         with:
-          context: containers/client/
+          context: .
+          file: containers/services/Dockerfile
           push: ${{ github.event_name != 'pull_request' && github.repository == 'DIRACGrid/diracx' && github.ref_name == 'main' }}
-          tags: ghcr.io/diracgrid/diracx/client:dev
+          tags: ghcr.io/diracgrid/diracx/services:dev
           platforms: linux/amd64,linux/arm64
-          build-args: |
-            EXTRA_PACKAGES_TO_INSTALL=git+https://github.com/DIRACGrid/DIRAC.git@integration#egg=diraccommon\&subdirectory=dirac-common
-      - name: Build and push services (dev)
+      - name: Build and push client (dev)
         uses: docker/build-push-action@v6
         with:
-          context: containers/services/
+          context: .
+          file: containers/client/Dockerfile
           push: ${{ github.event_name != 'pull_request' && github.repository == 'DIRACGrid/diracx' && github.ref_name == 'main' }}
-          tags: ghcr.io/diracgrid/diracx/services:dev
+          tags: ghcr.io/diracgrid/diracx/client:dev
           platforms: linux/amd64,linux/arm64
-          build-args: |
-            EXTRA_PACKAGES_TO_INSTALL=git+https://github.com/DIRACGrid/DIRAC.git@integration#egg=diraccommon\&subdirectory=dirac-common
 
   update-charts:
     name: Update Helm charts

.github/workflows/main.yml

@@ -121,38 +121,17 @@ jobs:
         with:
           cache: false
           environments: ${{ matrix.extension == 'diracx' && 'default' || 'default-gubbins' }}
-      - name: Build gubbins wheels
-        if: ${{ matrix.extension == 'gubbins' }}
-        run: |
-          for pkg_dir in $PWD/diracx-*; do
-            echo "Building $pkg_dir"
-            pixi exec python-build --outdir $PWD/extensions/containers/services/ $pkg_dir
-          done
-          # Also build the diracx metapackage
-          pixi exec python-build --outdir $PWD/extensions/containers/services/ .
-          # And build the gubbins package
-          for pkg_dir in $PWD/extensions/gubbins/gubbins-*; do
-            # Skip the testing package
-            if [[ "${pkg_dir}" =~ .*testing.* ]];
-            then
-              echo "Do not build ${pkg_dir}";
-              continue;
-            fi
-            echo "Building $pkg_dir"
-            pixi exec python-build --outdir $PWD/extensions/containers/services/ $pkg_dir
-          done
       - name: Set up Docker Buildx
         if: ${{ matrix.extension == 'gubbins' }}
         uses: docker/setup-buildx-action@v3
       - name: Build container for gubbins
         if: ${{ matrix.extension == 'gubbins' }}
         uses: docker/build-push-action@v6
         with:
-          context: extensions/containers/services
+          context: extensions/gubbins
+          file: extensions/containers/services/Dockerfile
           tags: gubbins/services:dev
           outputs: type=docker,dest=/tmp/gubbins_services_image.tar
-          build-args: |
-            EXTENSION_CUSTOM_SOURCES_TO_INSTALL=/bindmount/gubbins_db*.whl,/bindmount/gubbins_logic*.whl,/bindmount/gubbins_routers*.whl,/bindmount/gubbins_client*.whl
       - name: Load image
         if: ${{ matrix.extension == 'gubbins' }}
         run: |

.gitignore

@@ -97,7 +97,6 @@ docs/source/_build
 
 # pixi environments
 .pixi
-pixi.lock
 *.egg-info
 docs/templates/_builtin_markdown.jinja
 

.pre-commit-config.yaml

@@ -28,6 +28,7 @@ repos:
       - id: check-yaml
         args: ["--unsafe"]
       - id: check-added-large-files
+        exclude: pixi\.lock$
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: "v0.15.2"
@@ -66,6 +67,7 @@ repos:
     hooks:
       - id: codespell
         args: ["-w"]
+        exclude: pixi\.lock$
 
   - repo: https://github.com/adamchainz/blacken-docs
     rev: 1.20.0

containers/client/Dockerfile

@@ -1,12 +1,33 @@
-FROM ghcr.io/diracgrid/diracx/client-base
+FROM ghcr.io/prefix-dev/pixi:latest AS build
 
-ARG EXTRA_PACKAGES_TO_INSTALL
+WORKDIR /app
+COPY pixi.toml pixi.lock ./
 
-RUN --mount=type=bind,source=.,target=/bindmount DIRACX_CUSTOM_SOURCE_PREFIXES=/bindmount /entrypoint.sh bash -ec "pip install --no-deps ${EXTRA_PACKAGES_TO_INSTALL} && echo 'Running pip check' && pip check"
+# Copy source directories needed for path-based installs
+COPY diracx-core/ diracx-core/
+COPY diracx-client/ diracx-client/
+COPY diracx-api/ diracx-api/
+COPY diracx-cli/ diracx-cli/
+COPY diracx-testing/ diracx-testing/
+COPY pyproject.toml ./
 
-# In many clusters the container is ran as a random uid for security reasons.
-# If we mark the conda directory as group 0 and give it group write permissions
-# then we're still able to manage the environment from inside the container.
-USER 0
-RUN chown -R $MAMBA_USER:0 /opt/conda && chmod -R g=u /opt/conda
-USER $MAMBA_USER
+# Switch to non-editable installs (same workaround as CI)
+RUN sed -i 's@editable = true@editable = false@g' pixi.toml
+
+RUN pixi install --locked -e container-client
+
+# Generate activation script
+RUN pixi shell-hook -e container-client > /activate.sh
+
+FROM ubuntu:24.04
+
+# Copy the installed environment
+COPY --from=build /app/.pixi/envs/container-client /app/.pixi/envs/container-client
+COPY --from=build /activate.sh /activate.sh
+
+# In many clusters the container is run as a random uid for security reasons.
+RUN chmod -R g=u /app/.pixi
+
+# Use tini as init (installed by pixi in the env)
+ENTRYPOINT ["/app/.pixi/envs/container-client/bin/tini", "--", \
+            "/bin/bash", "-c", "source /activate.sh && exec \"$@\"", "--"]

containers/services/Dockerfile

@@ -1,12 +1,38 @@
-FROM ghcr.io/diracgrid/diracx/services-base
+FROM ghcr.io/prefix-dev/pixi:latest AS build
 
-ARG EXTRA_PACKAGES_TO_INSTALL
+WORKDIR /app
+COPY pixi.toml pixi.lock ./
 
-RUN --mount=type=bind,source=.,target=/bindmount DIRACX_CUSTOM_SOURCE_PREFIXES=/bindmount /entrypoint.sh bash -ec "pip install --no-deps ${EXTRA_PACKAGES_TO_INSTALL} && echo 'Running pip check' && pip check"
+# Copy source directories needed for path-based installs
+COPY diracx-core/ diracx-core/
+COPY diracx-db/ diracx-db/
+COPY diracx-logic/ diracx-logic/
+COPY diracx-routers/ diracx-routers/
+COPY diracx-testing/ diracx-testing/
+COPY pyproject.toml ./
 
-# In many clusters the container is ran as a random uid for security reasons.
-# If we mark the conda directory as group 0 and give it group write permissions
-# then we're still able to manage the environment from inside the container.
-USER 0
-RUN chown -R $MAMBA_USER:0 /opt/conda && chmod -R g=u /opt/conda
-USER $MAMBA_USER
+# Switch to non-editable installs (same workaround as CI)
+RUN sed -i 's@editable = true@editable = false@g' pixi.toml
+
+RUN pixi install --locked -e container-services
+
+# Generate activation script
+RUN pixi shell-hook -e container-services > /activate.sh
+
+FROM ubuntu:24.04
+
+EXPOSE 8000
+
+# Copy the installed environment
+COPY --from=build /app/.pixi/envs/container-services /app/.pixi/envs/container-services
+COPY --from=build /activate.sh /activate.sh
+
+# In many clusters the container is run as a random uid for security reasons.
+# If we mark the environment directory as group 0 and give it group write
+# permissions then we're still able to manage the environment from inside the
+# container.
+RUN chmod -R g=u /app/.pixi
+
+# Use tini as init (installed by pixi in the env)
+ENTRYPOINT ["/app/.pixi/envs/container-services/bin/tini", "--", \
+            "/bin/bash", "-c", "source /activate.sh && exec \"$@\"", "--"]

docs/dev/explanations/components/index.md

@@ -81,57 +81,48 @@ flowchart BT
 
 ## Container Images
 
-DiracX utilizes a structured approach to containerization:
+DiracX container images are built using [pixi](https://pixi.sh/) environments defined in `pixi.toml`. All dependencies — both conda and PyPI packages — are resolved via the committed `pixi.lock` file, ensuring reproducible builds with exact version parity between development and production.
 
-1. **Base Image**:
+### Architecture
 
-    - All container images start from `diracx/base`.
+Each container image is built using a multi-stage Dockerfile:
 
-2. **Specialized Base Images**:
+1. **Build stage**: Uses `ghcr.io/prefix-dev/pixi` to install a pixi environment from the lock file with `pixi install --locked`.
+2. **Runtime stage**: Uses a minimal `ubuntu:24.04` base image. The installed pixi environment is copied from the build stage. [Tini](https://github.com/krallin/tini) is used as the init process for proper signal handling.
 
-    - `diracx/services-base`
-    - `diracx/tasks-base`
-    - `diracx/client-base`
+The container environments are defined in `pixi.toml` alongside the development environments, sharing the same solve group to guarantee identical dependency versions:
 
-3. **Image Versioning and Building**:
+- **`container-services`**: Includes `diracx-routers`, `diracx-logic`, `diracx-db`, and `diracx-core` plus runtime dependencies (tini, CA certificates, git).
+- **`container-client`**: Includes `diracx-cli`, `diracx-api`, `diracx-client`, and `diracx-core` plus runtime dependencies.
 
-    - Images are built periodically (e.g., every Monday) and tagged as `YYYY.MM.DD.P`.
-    - A DiracX release triggers the creation of new `DiracXService`, `diracx/tasks`, and `diracx/client` images, based on specific `diracx/base` tags.
-    - This approach ensures stability in production environments.
-    - For testing purposes, the `latest` base images are used, with dependencies installed via `pip install`.
+### Building
 
-See this diagram for an example of how this looks in practice:
+Container images are self-contained — the Dockerfile copies source code and uses `pixi install --locked` to resolve everything from the lock file. No separate base images or wheel-building steps are needed:
 
 ```
-                       ┌──────────────────────────┐
-                 ┌─────┤ diracx/base:YYYY.MM.DD.P ├─────┐
-                 │     └──────────────────────────┘     │
-                 │                                      │
-┌────────────────▼──────────────────┐  ┌────────────────▼───────────────┐
-│ diracx/services-base:YYYY.MM.DD.P │  │ diracx/tasks-base:YYYY.MM.DD.P │
-└────────────────┬──────────────────┘  └────────────────┬───────────────┘
-                 │                                      │
-     ┌───────────▼────────────┐              ┌──────────▼──────────┐
-     │ diracx/services:v0.X.Y │              │ diracx/tasks:v0.X.Y │
-     └────────────────────────┘              └─────────────────────┘
-
+┌──────────────────────────────────────────┐
+│           pixi build stage               │
+│  pixi.toml + pixi.lock + source → env    │
+└────────────────┬─────────────────────────┘
+                 │
+     ┌───────────▼────────────┐
+     │  ubuntu:24.04 runtime  │
+     │  + pixi env copied in  │
+     └────────────────────────┘
 ```
 
-### Dependencies
-
-- There is a noted duplication between `setup.cfg` and `environment.yaml`.
-- The `diracx/base` image is built from a Dockerfile with `environment.yml`, primarily defining the Python version and `dirac_environment.yaml` containing the DIRAC specific dependencies. The latter is there as a "temporary" thing.
-- The `diracx/services-base` and `diracx/tasks-base` images extend `diracx/base` with additional Dockerfiles and `environment.yml`, tailored to their specific needs.
-- The `diracx/services` and `diracx/tasks` images are further built upon their respective base images, adding necessary diracx packages through `pip install --no-dependencies`.
+### Versioning
 
-### Entrypoint
+- Release builds are tagged with the version (e.g., `ghcr.io/diracgrid/diracx/services:v0.X.Y`).
+- Development builds from `main` are tagged as `dev`.
 
-TODO: document the entry point
+### Server Entry Points
 
 - `diracx-routers`:
     - `diracx.diracx_min_client_version` entry-point defines the diracx minimum client version required by the server to prevent issues. This also searches for extension names instead of `diracx`. The minimum version number has to be updated in `diracx-routers/src/__init.py__`
 
 ## Extensions
 
-- Extensions will extend one or more of `diracx`, `diracx-routers`, `diracx-tasks` images (e.g. `lhcbdiracx`, `lhcbdiracx-routers`, `lhcbdiracx-tasks`).
-- Extensions provide a corresponding container image based on a specific release of the corresponding DiracX image.
+Extensions (e.g., Gubbins, LHCbDIRACX) provide their own `pixi.toml` and `pixi.lock` with container environments that pull in both the extension and upstream DiracX packages transitively.
+
+The extension container Dockerfile follows the same multi-stage pixi pattern, built from the extension's own source directory.

extensions/containers/client/Dockerfile

@@ -1,13 +1,33 @@
-FROM ghcr.io/diracgrid/diracx/client:dev
+FROM ghcr.io/prefix-dev/pixi:latest AS build
 
-#Extension
-ENV GUBBINS_IMAGE_PACKAGES=core,client,api,cli,.
+WORKDIR /app
+COPY pixi.toml pixi.lock ./
 
-RUN --mount=type=bind,source=.,target=/bindmount GUBBINS_CUSTOM_SOURCE_PREFIXES=/bindmount /entrypoint.sh bash -exc "ls /bindmount && echo 'Running pip check' && pip check"
+# Copy gubbins source directories
+COPY gubbins-core/ gubbins-core/
+COPY gubbins-client/ gubbins-client/
+COPY gubbins-api/ gubbins-api/
+COPY gubbins-cli/ gubbins-cli/
+COPY gubbins-testing/ gubbins-testing/
+COPY pyproject.toml ./
 
-# # In many clusters the container is ran as a random uid for security reasons.
-# # If we mark the conda directory as group 0 and give it group write permissions
-# # then we're still able to manage the environment from inside the container.
-USER 0
-RUN chown -R $MAMBA_USER:0 /opt/conda && chmod -R g=u /opt/conda
-USER $MAMBA_USER
+# Switch to non-editable installs (same workaround as CI)
+RUN sed -i 's@editable = true@editable = false@g' pixi.toml
+
+RUN pixi install --locked -e container-client
+
+# Generate activation script
+RUN pixi shell-hook -e container-client > /activate.sh
+
+FROM ubuntu:24.04
+
+# Copy the installed environment
+COPY --from=build /app/.pixi/envs/container-client /app/.pixi/envs/container-client
+COPY --from=build /activate.sh /activate.sh
+
+# In many clusters the container is run as a random uid for security reasons.
+RUN chmod -R g=u /app/.pixi
+
+# Use tini as init (installed by pixi in the env)
+ENTRYPOINT ["/app/.pixi/envs/container-client/bin/tini", "--", \
+            "/bin/bash", "-c", "source /activate.sh && exec \"$@\"", "--"]