LDMX-Software · tomeichlersmith · Mar 12, 2025 · Mar 5, 2025 · Mar 5, 2025 · Mar 5, 2025
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -8,24 +8,28 @@ assignees: ''
 ---
 
 **Describe the bug**
-A clear and concise description of what the bug is.
+<!-- A clear and concise description of what the bug is. -->
 
 **To Reproduce**
+<!--
 Steps to reproduce the behavior:
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
+-->
 
 **Expected behavior**
-A clear and concise description of what you expected to happen.
+<!-- A clear and concise description of what you expected to happen. -->
 
 **Screenshots**
-If applicable, add screenshots to help explain your problem.
+<!-- If applicable, add screenshots to help explain your problem. -->
 
-**What tag of the container are you using?**
+**Image Details**
+Output of `denv config print`:
 
-**What application are you using to run the container?**
+Specify Image Version:
+<!-- https://ldmx-software.github.io/dev-build-context/image-version.html has instructions on how to do this -->
 
 **Additional context**
-Add any other context about the problem here.
+<!-- Add any other context about the problem here. -->
diff --git a/.github/ISSUE_TEMPLATE/package_request.md b/.github/ISSUE_TEMPLATE/package_request.md
@@ -8,16 +8,18 @@ assignees: ''
 ---
 
 ## Is your request related to a problem? Please describe.
-A clear and concise description of what the problem is. Ex. I'm used to using this package when [...]
+<!-- A clear and concise description of what the problem is. Ex. I'm used to using this package when... -->
 
 ## Describe the solution you'd like. What packages do you want installed?
-A clear and concise description of what you want to happen.
+<!-- A clear and concise description of what you want to happen. -->
 
-**The Development Container is based on Ubuntu 22.04. How do you install your necessary packages on Ubuntu?**
+**The Development Image is based on Ubuntu 24.04. How do you install your necessary packages on Ubuntu?**
+<!--
 A description and list of commands to run, for example
 ```
 apt-get install my-package
 ```
+-->
 
 **Additional context**
-Add any other context or screenshots about the feature request here.
+<!-- Add any other context or screenshots about the feature request here.  -->
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,35 +1,31 @@
 
 I am adding a new package to the container, here are the details.
 
-### What new packages does this PR add to the development container?
+### What new packages does this PR add to the development image?
 - package1
 - package2
 
 ## Check List
 - [ ] I successfully built the container using docker
-```
-# outline of container build instructions
-cd docker
+<!--
+cd dev-build-context 
 git checkout my-updates
 docker build . -t ldmx/local:temp-tag
-```
+-->
 - [ ] I was able to build ldmx-sw using this new container build
-```
+<!--
 # outline of build instructions
-ldmx-container-pull local temp-tag
 cd ldmx-sw
-mkdir build
-cd build
-ldmx cmake ..
-ldmx make install
-```
+just use ldmx/local:temp-tag
+just configure
+just build
+-->
 - [ ] I was able to test run a small simulation and reconstruction inside this container
-```
+<!--
 # outline of test instructions
-cd $LDMX_BASE/ldmx-sw/build
-ldmx ctest
-cd ..
-for c in `ls ldmx-sw/*/test/*.py`; ldmx fire $c; done
-```
-- [ ] I was able to successfully use the new packages. Explain what you did to test them below:
-
+cd ldmx-sw/build
+denv ctest
+denv LDMX_NUM_EVENTS=10 LDMX_RUN_NUMBER=1 fire ../.github/validation_samples/inclusive/config.py
+-->
+- [ ] I was able to successfully use the new packages.
+<!-- Explain what you did to test them below. -->
diff --git a/.github/install-mdbook b/.github/install-mdbook
@@ -0,0 +1,52 @@
+#!/bin/sh
+
+set -o errexit
+set -o nounset
+
+# Assume the environment variables MDBOOK_VERSION and MDBOOK_ADMONISH_VERSION are set
+
+# Download a tar ball and then unpack it into a destination
+# Arguments
+#   1 - URL for the .tar.gz to download
+#   2 - target directory to unpack into
+download() {
+  wget -q -O - "${1}" | tar -xz --directory "${2}"
+}
+
+help() {
+  cat <<\HELP
+
+ USAGE:
+  ./.github/install-mdbook [target]
+
+ ARGUMENTS:
+  target : directory to download mdbook and mdbook-admonish into
+
+ ENVIRONMENT:
+  We assume that MDBOOK_VERSION and MDBOOK_ADMONISH_VERSION are set
+  to the desired versions like how it is done in the CI workflow.
+
+HELP
+}
+
+target="${HOME}/.local/bin"
+while [ "${#}" -gt 0 ]; do
+  case "${1}" in
+    -h|--help)
+      help
+      exit 0
+      ;;
+    *)
+      target="${1}"
+      ;;
+  esac
+  shift
+done
+
+mkdir -p "${target}"
+download \
+  https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz \
+  "${target}"
+download \
+  https://github.com/tommilligan/mdbook-admonish/releases/download/v${MDBOOK_ADMONISH_VERSION}/mdbook-admonish-v${MDBOOK_ADMONISH_VERSION}-x86_64-unknown-linux-gnu.tar.gz \
+  "${target}"
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -12,6 +12,7 @@ on:
       - '.github/workflows/mdbook.yml'
       - '.github/workflows/ldmx-sw-dependabot.yml'
       - '.github/workflows/README.md'
+      - '.github/install-mdbook'
     branches:
       - "**"
     tags:

diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml
@@ -35,17 +35,19 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Install mdBook
-        run: |
-          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
-          rustup update
-          cargo install --version ${MDBOOK_VERSION} --locked mdbook
-          cargo install --version ${MDBOOK_ADMONISH_VERSION} --locked mdbook-admonish
+        run: ./.github/install-mdbook
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
       - name: Build with mdBook
         run: mdbook build
         working-directory: docs
+      - name: Check Links
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          fail: true
+          args: ./docs/book
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

diff --git a/README.md b/README.md
@@ -1,46 +1,62 @@
+<!-- 
+DEVELOPER NOTICE
+
+Since this file is not in docs/src but we still copy it there for creating the website,
+we need to have all links in this file be the full link to the website so that the
+website works properly.
+
+Instead of
+    [my link](docs/src/page.md)
+Do
+    [my link](https://ldmx-software.github.io/dev-build-context/page.html)
+-->
+
 # Development Image Build Context
 The build context for the `ldmx/dev` images used for developing and running ldmx-sw.
 
 <p align="center">
     <a href="http://perso.crans.org/besson/LICENSE.html" alt="GPLv3 license">
         <img src="https://img.shields.io/badge/License-GPLv3-blue.svg" />
     </a>
-    <a href="https://github.com/LDMX-Software/dev-build-context/actions" alt="Actions">
-        <img src="https://github.com/LDMX-Software/dev-build-context/workflows/CI/badge.svg" />
+    <a href="https://github.com/LDMX-Software/dev-build-context/actions/workflows/ci.yml" alt="Actions">
+        <img src="https://github.com/LDMX-Software/dev-build-context/actions/workflows/ci.yml/badge.svg" />
     </a>
     <a href="https://hub.docker.com/r/ldmx/dev" alt="DockerHub">
-        <img src="https://img.shields.io/github/v/release/LDMX-Software/docker" />
+        <img src="https://img.shields.io/github/v/release/LDMX-Software/dev-build-context" />
     </a>
 </p>
 
-There is a corresponding workflow in [ldmx-sw](https://github.com/LDMX-Software/ldmx-sw) that generates a [production docker container](https://hub.docker.com/repository/docker/ldmx/pro) using the container generated by this build context as a base image.
-This production container already has ldmx-sw built and installed on it and assumes the user wants to run the application.
-
-### Use in ldmx-sw
+There is a corresponding workflow in [ldmx-sw](https://github.com/LDMX-Software/ldmx-sw) that generates a [production image](https://hub.docker.com/r/ldmx/pro) using the image generated by this build context as a base image.
+This production image already has ldmx-sw built and installed on it and assumes the user wants to run the application.
 
-In _ldmx-sw_, an [environment script](https://github.com/LDMX-Software/ldmx-sw/blob/master/scripts/ldmx-env.sh) is defined in `bash` to setup the environment for both `docker` and `singularity` correctly.
-A description of this setup process is given for both [docker](docs/use_with_docker.md) and [singularity](docs/use_with_singularity.md) if you desire more information.
+## Usage
+The image is designed to be used with [`denv`](https://tomeichlersmith.github.io/denv/)
+which provides support for Docker, Podman, and Apptainer.
 
-## Current Container Configuration
+## Software in Image
 
 Software Package | Version | Construction Process
 ---|---|---
-[Ubuntu Server](https://ubuntu.com/) | 22.04 | Base Image
-[Python](https://www.python.org/) | 3.10.6 | From Ubuntu Repos
-[cmake](https://cmake.org/) | 3.22.1 | From Ubuntu Repos
-[Boost](https://www.boost.org/doc/libs/1_74_0/) | 1.74.0 | From Ubuntu Repos
-[XercesC](http://xerces.apache.org/xerces-c/) | 3.2.4 | Built from source
-[Pythia6](https://pythia.org/pythia6/) | 6.428 | Built from source
-[ROOT](https://root.cern.ch/) | 6.22/08 | Built from source
-[Geant4](https://geant4.web.cern.ch/node/1) | [LDMX.10.2.3\_v0.5](https://github.com/LDMX-Software/geant4/tree/LDMX.10.2.3_v0.5) | Built from source
+[Ubuntu Server](https://ubuntu.com/) | 24.04 | Base Image
+[Python](https://www.python.org/) | 3.12.3 | From Ubuntu Repos
+[cmake](https://cmake.org/) | 3.28.3 | From Ubuntu Repos
+[Boost](https://www.boost.org/doc/libs/1_74_0/) | 1.83.0 | From Ubuntu Repos
+[XercesC](http://xerces.apache.org/xerces-c/) | 3.3.0 | Built from source
+[LHAPDF](https://www.lhapdf.org/) | 6.5.5 | Built from source
+[Pythia8](https://pythia.org/) | 8.313 | Built from source
+[ROOT](https://root.cern.ch/) | 6.34.04 | Built from source
+[Geant4](https://geant4.web.cern.ch/) | [LDMX.10.2.3\_v0.6](https://github.com/LDMX-Software/geant4/tree/LDMX.10.2.3_v0.6) | Built from source
 [Eigen](https://eigen.tuxfamily.org/index.php?title=Main_Page) | 3.4.0 | Built from source
-[LHAPDF](https://lhapdf.hepforge.org/) | 6.5.3 | Built from source
-[GENIE](http://www.genie-mc.org/) | 3.02.00 | Built from source
+[HEPMC3](https://hepmc.web.cern.ch) | 3.3.0 | Built from source
+[GENIE](http://www.genie-mc.org/) Generator | [3.02.02-ldmx](https://github.com/wesketchum/Generator/releases/tag/R-3_04_02-ldmx) | Built from source
+[GENIE](http://www.genie-mc.org/) Reweight | 1.04.00 | Built from Source
 [Catch2](https://github.com/catchorg/Catch2) | 3.3.1 | Built from source
 [ONNX Runtime](https://github.com/microsoft/onnxruntime) | 1.15.0 | Download pre-built binaries
 
-A detailed list of all packages installed from ubuntu repositories is given [here](docs/ubuntu-packages.md),
-and documentation on the workflow and runner used to build the image is [here](docs/runner.md).
+A detailed list of all packages installed from ubuntu repositories is given
+[here](https://ldmx-software.github.io/dev-build-context/ubuntu-packages.html),
+and documentation on the workflow and runner used to build the image is
+[here](https://ldmx-software.github.io/dev-build-context/runner.html).
 
 ### Python Packages for Analyses
 Installed in Python 3.

diff --git a/ci/interop/README.md b/ci/interop/README.md
diff --git a/ci/interop/README.md b/ci/interop/README.md
@@ -0,0 +1 @@
+../../docs/src/interop.md
diff --git a/docs/book.toml b/docs/book.toml
@@ -10,8 +10,8 @@ create-missing = false
 
 [output.html]
 mathjax-support = true
-git-repository-url = "https://github.com/LDMX-Software/docker/tree/main/"
-edit-url-template = "https://github.com/LDMX-Software/docker/edit/main/docs/{path}"
+git-repository-url = "https://github.com/LDMX-Software/dev-build-context/tree/main/"
+edit-url-template = "https://github.com/LDMX-Software/dev-build-context/edit/main/docs/{path}"
 additional-css = ["mdbook-admonish.css"]
 
 [preprocessor]

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -2,15 +2,16 @@
 
 [Welcome](README.md)
 
-# User Guide
+# Using
 - [Custom Geant4](custom-geant4.md)
+- [Custom Acts](custom-acts.md)
 - [Parallel Containers](parallel_containers.md)
+- [Determing an Image's Version](image-version.md)
 
-# Developer's Guide
+# Developing
 - [Contributing](contributing.md)
 - [Ubuntu Packages](ubuntu-packages.md)
-- [Running the Image](usage.md)
-  - [With Docker](use_with_docker.md)
-  - [With Singularity](use_with_singularity.md)
+- [Runtime Configuration](runtime-config.md)
 - [GitHub Workflows](workflows.md)
+  - [Legacy Interop](interop.md)
   - [Self-Hosted Runner](runner.md)