Merge pull request #891 from SyneRBI/docs-docker

.github/workflows/docker.yml

@@ -40,12 +40,13 @@ jobs:
           ghcr.io/synerbi/sirf
         flavor: |
           latest=auto
-          suffix=${{ matrix.type == 'gpu' && 'gpu,onlatest=true' || '' }}
+          suffix=${{ matrix.type == 'gpu' && '-gpu,onlatest=true' || '' }}
         tags: |
           type=edge
           type=semver,pattern={{version}}
           type=semver,pattern={{major}}.{{minor}}
           type=semver,pattern={{major}}
+          type=raw,value=jupyter,enable=${{ startsWith(github.ref, 'refs/tags') }}
         labels: |
           org.opencontainers.image.licenses=Apache-2.0${{ matrix.type == 'gpu' && ' AND BSD-3-Clause AND GPL-3.0' || '' }}
     - uses: docker/login-action@v3
@@ -89,7 +90,7 @@ jobs:
       run: |
         # rebuild sirf image
         ./docker/compose.sh -bR${{ matrix.type == 'gpu' && 'g' || 'c' }}
-        image=synerbi/sirf:jupyter${{ steps.pull.outputs.suffix }}
+        image=synerbi/sirf:latest${{ steps.pull.outputs.suffix }}
         echo "image=$image" >> "$GITHUB_OUTPUT"
         # tag potentially newer core image
         docker tag synerbi/jupyter:scipy-${{ matrix.type }} ${{ steps.pull.outputs.core_image }}
@@ -130,7 +131,7 @@ jobs:
           ghcr.io/synerbi/sirf
         flavor: |
           latest=false
-          suffix=${{ matrix.type == 'gpu' && 'gpu,onlatest=true' || '' }}
+          suffix=${{ matrix.type == 'gpu' && '-gpu,onlatest=true' || '' }}
         tags: devel
         labels: |
           org.opencontainers.image.licenses=Apache-2.0${{ matrix.type == 'gpu' && ' AND BSD-3-Clause AND GPL-3.0' || '' }}
@@ -173,7 +174,7 @@ jobs:
       run: |
         # rebuild sirf image
         ./docker/compose.sh -dbR${{ matrix.type == 'gpu' && 'g' || 'c' }}
-        image=synerbi/sirf:jupyter-devel${{ steps.pull.outputs.suffix }}
+        image=synerbi/sirf:devel${{ steps.pull.outputs.suffix }}
         echo "image=$image" >> "$GITHUB_OUTPUT"
     - name: test CIL
       run: >

docker-compose.yml

@@ -41,7 +41,7 @@ services:
     BUILD_GPU: 0
  sirf:
   container_name: sirf  # for scaling, comment this out https://github.com/docker/compose/issues/3729
-  image: synerbi/sirf:jupyter
+  image: synerbi/sirf:latest
   build:
    context: .
    args:

docker/README.md

@@ -11,20 +11,35 @@ The image contains SIRF & all dependencies required by JupyterHub.
 
 ```sh
 # CPU version
-docker run --rm -it -p 9999:8888 ghcr.io/synerbi/sirf:jupyter
+docker run --rm -it -p 9999:8888 ghcr.io/synerbi/sirf:latest
 # GPU version
-docker run --rm -it -p 9999:8888 --gpus all ghcr.io/synerbi/sirf:jupyter-gpu
+docker run --rm -it -p 9999:8888 --gpus all ghcr.io/synerbi/sirf:latest-gpu
 ```
 
-The Jupyter notebook should be accessible at <https://localhost:9999>.
+> [!TIP]
+> docker tag | git branch/tag
+> :---|:---
+> `latest`, `latest-gpu` | [latest tag `v*.*.*`](https://github.com/SyneRBI/SIRF-SuperBuild/releases/latest)
+> `M`, `M.m`, `M.m.p`, `M-gpu`, `M.m-gpu`, `M.m.p-gpu` | tag `vM.m.p`
+> `edge`, `edge-gpu` | `master`
+> `devel`, `devel-gpu` | `master` with `cmake -DDEVEL_BUILD=ON -DBUILD_CIL=ON`
+>
+> See [`ghcr.io/synerbi/sirf`](https://github.com/SyneRBI/SIRF-SuperBuild/pkgs/container/sirf) for a full list of tags.
+>
+> The [`docker.yml` workflow](../.github/workflows/docker.yml) builds & pushes all the docker tags above.
+> Additionally, `core` & `core-gpu` intermediate (cache) docker tags are built & pushed by the workflow, but are not intended for users.
+
+The workflow will also build & test all PRs (without pushing any new image tags).
+
+The Jupyter notebook should be accessible at <http://localhost:9999>.
 
 > [!WARNING]
 > To sync the container user & host user permissions (useful when sharing folders), use `--user` and `--group-add`.
 >
 > ```sh
 > docker run --rm -it -p 9999:8888 --user $(id -u) --group-add users \
 >   -v ./devel:/home/jovyan/work \
->   ghcr.io/synerbi/sirf:jupyter
+>   ghcr.io/synerbi/sirf:latest
 > ```
 
 More config: <https://jupyter-docker-stacks.readthedocs.io/en/latest/using/common.html#user-related-configurations>.
@@ -35,7 +50,7 @@ More config: <https://jupyter-docker-stacks.readthedocs.io/en/latest/using/commo
 > ```sh
 > docker run --rm -it -p 9999:8888 --user $(id -u) --group-add users \
 >   -v /mnt/data:/share -e SIRF_DOWNLOAD_DATA_ARGS="-pm -D /share" \
->   ghcr.io/synerbi/sirf:jupyter
+>   ghcr.io/synerbi/sirf:latest
 > ```
 
 ### Extending
@@ -44,9 +59,9 @@ You can build custom images on top of the SIRF ones, likely needing to switch be
 
 ```Dockerfile
 # CPU version
-# FROM synerbi/sirf:jupyter
+# FROM synerbi/sirf:latest
 # GPU version
-FROM synerbi/sirf:jupyter-gpu
+FROM synerbi/sirf:latest-gpu
 USER root
 RUN mamba install pytorch && fix-permissions "${CONDA_DIR}" /home/${NB_USER}
 USER ${NB_UID}
@@ -154,3 +169,6 @@ Note that this cache is different from the "normal" `ccache` of your host. (If y
   + Install [`requirements.yml`](requirements.yml)
   + Clone & setup <https://github.com/SyneRBI/SIRF-Exercises> & <https://github.com/TomographicImaging/CIL-Demos>
   + Set some environment variables (e.g. `PYTHONPATH=/opt/SIRF-SuperBuild/INSTALL/python`, `OMP_NUM_THREADS=$(( cpu_count/2 ))`)
+
+> [!NOTE]
+> `synerbi/jupyter:*` are only intermediate (cache) images not intended for users.

docker/compose.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 print_help(){
   cat <<EOF
-Creates images: synerbi/sirf:jupyter, synerbi/sirf:jupyter-gpu
+Creates images: synerbi/sirf:latest, synerbi/sirf:latest-gpu
 Also creates intermediate (temp) images: synerbi/jupyter
 
 Usage: $0 [options] [-- [docker compose options]]

docker/devel/shared.txt

@@ -4,7 +4,7 @@ Host:
 
 `SIRF-SuperBuild/docker/devel`
 
-Docker container (synerbi/sirf:jupyter):
+Docker container (synerbi/sirf:latest):
 
 `/home/jovyan/work`
 

docker/docker-compose.devel-gpu.yml

@@ -3,6 +3,6 @@ services:
  sirf-build:
   image: synerbi/jupyter:sirf-build-devel-gpu
  sirf:
-  image: synerbi/sirf:jupyter-devel-gpu
+  image: synerbi/sirf:devel-gpu
   build:
    cache_from: [synerbi/jupyter:sirf-build-devel-gpu]

docker/docker-compose.devel.yml

@@ -9,7 +9,7 @@ services:
      -DBUILD_CIL=ON
  sirf:
   container_name: sirf  # for scaling, comment this out https://github.com/docker/compose/issues/3729
-  image: synerbi/sirf:jupyter-devel
+  image: synerbi/sirf:devel
   build:
    context: .
    args:

docker/docker-compose.gpu.yml

@@ -29,7 +29,7 @@ services:
     Gadgetron_USE_CUDA: "ON"
  sirf:
   deploy: {resources: {reservations: {devices: [{driver: nvidia, count: all, capabilities: [gpu]}]}}}
-  image: synerbi/sirf:jupyter-gpu
+  image: synerbi/sirf:latest-gpu
   build:
    args:
     BASE_CONTAINER: synerbi/jupyter:scipy-gpu