Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ShipSoft/FairShip/llms.txt

Use this file to discover all available pages before exploring further.

Docker provides a fully self-contained FairShip environment that is independent of the host operating system. It is particularly useful when you need a reproducible, stateless snapshot for debugging a specific problem, when submitting jobs to an HTCondor or other cluster system that requires a container image, or when you want a strict boundary between FairShip’s software stack and your local machine. For day-to-day interactive development, the pixi workflow or CVMFS-based setup are faster and more ergonomic choices.
Docker is not the recommended workflow for local development. Use pixi or CVMFS instead. Additionally, the container ENTRYPOINT runs alienv enter --shellrc FairShip/latest, which requires an interactive terminal — you must pass the -t flag to docker run or alienv will fail to detect a terminal and refuse to start.

​
Image Sources

FairShip images are based on olantwin/ship-base:220713, a minimal image maintained at github.com/olantwin/ship-base that provides the full aliBuild software stack. Pre-built FairShip images are available on Docker Hub at hub.docker.com/r/olantwin/fairship if you want to skip the local build entirely.

​
Building the Image

1

Clone the repository

The Dockerfile is included in the FairShip repository. Clone it to get both the build recipe and the source code that will be compiled into the image:
git clone https://github.com/ShipSoft/FairShip.git
cd FairShip
2

Build the Docker image

Run docker build from the repository root. The -t fairship flag gives the image a convenient local name:
docker build -t fairship .
The build copies the FairShip source into the image and compiles it with aliBuild, which can take a significant amount of time on the first run. Subsequent builds reuse Docker layer cache where possible.

​
Running the Container

Start a shell inside the container. The --rm flag removes the container when you exit, keeping your Docker state clean:
docker run -i -t --rm fairship /bin/bash
The container entrypoint (alienv enter --shellrc FairShip/latest) sets up the FairShip environment before dropping you into the shell. From there you can run simulations, reconstructions, and analyses exactly as you would in a native environment.

​
Dockerfile Reference

The Dockerfile at the repository root is intentionally minimal: 
# Base image maintained at https://github.com/olantwin/ship-base and available
# on Docker Hub: https://hub.docker.com/r/olantwin/ship-base/
#
# Prebuilt images available on Docker Hub at:
# https://hub.docker.com/r/olantwin/fairship/
FROM olantwin/ship-base:220713

# Copy FairShip scripts
COPY . /FairShip

# Build FairShip
RUN aliBuild -c shipdist/ build FairShip --no-local ROOT

# Setup environment. Setup the command that will be invoked when your docker
# image is run. Note that this requires running with `docker run -t` so that
# `alienv` detects an interactive terminal.
ENTRYPOINT alienv enter --shellrc FairShip/latest
The key points:
  • Base image olantwin/ship-base:220713 supplies the full aliBuild stack (ROOT, Geant4, FairRoot, etc.) so FairShip itself is the only package built from source.
  • --no-local ROOT tells aliBuild to use the ROOT already present in the base image rather than rebuilding it.
  • The ENTRYPOINT requires -t (allocate a pseudo-TTY) because alienv enter checks for an interactive terminal. Omitting -t causes the entrypoint to hang or fail.
If you need to build the image with a modified FairShip source, make your changes locally before running docker build. The COPY . /FairShip instruction copies the entire working tree, so uncommitted local changes are included in the image.

Build docs developers (and LLMs) love

Get started for freeTalk to us