EPIC Workflow

Dockerized build and view workflow for EPIC datasets served through episcope.

The build stage reads an EPIC input.yaml, runs the local CT2 edge pipeline, and writes an episcope-compatible ensemble under .build/ensemble. The view stage mounts that ensemble at /data, starts episcope with ParaView/trame, and opens the local browser.

The view-stage Dockerfile follows the same build pattern as Visualization/episcope/Dockerfile: it starts from kitware/paraview-for-ci:v6.1.0, creates the episcope virtual environment with pvpython -m venv, installs episcope into that environment, and launches with pvpython --venv /opt/episcope/.venv -m episcope.app --server.

Requirements

• Docker or a Docker-compatible container runtime.
• An EPIC project directory containing input.yaml.
• Build-stage inputs referenced by input.yaml, available from the project directory mount.

Docker Images

The wrapper uses these image repositories by default:

epic/epic-workflow-build
epic/epic-workflow-view

If you do not pass --tag, EPICWorkflow selects an architecture-specific tag for the current host: latest-arm64 on arm64/aarch64 machines and latest-amd64 on x86_64 machines.

Run Docker build commands from the EPICWorkflow directory:

cd Visualization/EPICWorkflow

Build both images for the local Docker platform:

make docker

Build both images for a specific architecture:

make docker-amd64
make docker-arm64

These targets build both build and view images for linux/amd64 and linux/arm64, then tag them with architecture suffixes:

epic/epic-workflow-build:latest-amd64
epic/epic-workflow-view:latest-amd64
epic/epic-workflow-build:latest-arm64
epic/epic-workflow-view:latest-arm64

On Apple Silicon, use make docker-arm64 before running ./EPICWorkflow without --tag. On x86_64 Linux, use make docker-amd64.

The view image intentionally mirrors the standalone episcope image and uses the Kitware ParaView CI base. If Docker reports a base-image platform warning while building the view image for arm64, that warning is from the upstream ParaView base image selection; the EPICWorkflow target still tags the result as latest-arm64 so the wrapper can find the locally built image.

Build only one stage:

make docker-build
make docker-view

Build only one stage for a specific architecture:

make docker-build PLATFORM=linux/arm64 ARCH_SUFFIX=-arm64
make docker-view PLATFORM=linux/arm64 ARCH_SUFFIX=-arm64

You can also pass Docker platform settings directly:

make docker PLATFORM=linux/amd64 ARCH_SUFFIX=-amd64
make docker PLATFORM=linux/arm64 ARCH_SUFFIX=-arm64

Rebuild after editing a Dockerfile or a copied script:

make docker-arm64

or, for only the view stage:

make docker-view PLATFORM=linux/arm64 ARCH_SUFFIX=-arm64

Check that the expected local images exist:

docker image ls epic/epic-workflow-build
docker image ls epic/epic-workflow-view

Tag and publish the current version from version.txt:

make docker-tag
make docker-push

For architecture-specific pushes, pass the same suffix used for the build:

make docker-push ARCH_SUFFIX=-amd64
make docker-push ARCH_SUFFIX=-arm64

Usage

Build a project:

./EPICWorkflow build /path/to/project

This mounts the project at /in, writes build artifacts to /path/to/project/.build, and leaves the episcope ensemble at /path/to/project/.build/ensemble.

View an already-built project:

./EPICWorkflow view /path/to/project

The viewer container serves episcope on container port 8080. The wrapper maps that to 127.0.0.1:8000 by default and opens the browser.

Inside the view container, Docker passes the default command --data /data --host 0.0.0.0 --port 8080 to the entrypoint. The entrypoint therefore runs:

pvpython --venv /opt/episcope/.venv -m episcope.app --server --data /data --host 0.0.0.0 --port 8080

Build and view:

./EPICWorkflow run /path/to/project

The wrapper accepts either a project directory containing .build/ensemble, a directory containing ensemble, or the ensemble directory itself.

Useful options:

./EPICWorkflow --dry-run run /path/to/project
./EPICWorkflow view --port 9000 /path/to/project
./EPICWorkflow --tag 0.2.0 run /path/to/project
./EPICWorkflow --tag latest-arm64 run /path/to/project
./EPICWorkflow --tag latest-amd64 run /path/to/project
./EPICWorkflow --rootless run /path/to/project

Pull the configured image tag:

./EPICWorkflow update

Print the build and view image versions:

./EPICWorkflow version

Build the Python source distribution for the wrapper:

make module