Merge pull request 'ci: enforce strict registry auth and optimize quarto builds' (#12) from push-qwnmlsqumxul into master

Reviewed-on: #12

Readme.md

@@ -82,7 +82,8 @@ These flags work alongside any mode:
 |------|--------|
 | `--stop-server` | Stop the stack and remove student containers, then exit |
 | `--update-lectures` | Rebuild the course website only (no Docker stop/start) |
-| `--build-obidoc` | Force rebuild of the obidoc documentation |
+| `--update-obidoc` | Rebuild the obidoc documentation only (no Docker stop/start) |
+| `--build-obidoc` | Force rebuild of obidoc documentation on next full start |
 
 ## Installation and first run
 
@@ -156,6 +157,48 @@ Packages are cached in `jupyterhub_volumes/builder/R_packages/`:
 - **Non-CRAN packages**: packages installed via `remotes::install_git()` or `remotes::install_github()` in your `.qmd` files are detected and pre-installed automatically before rendering.
 - **Clear the cache**: delete `jupyterhub_volumes/builder/R_packages/` to force a full reinstall.
 
+## OBITools documentation (obidoc)
+
+The OBITools4 documentation is built from the [`obitools4-doc`](https://github.com/metabarcoding/obitools4-doc) repository using Hugo and served as a static site at `http://localhost:8888/obidoc/`.
+
+### How it works
+
+The builder container clones the repository (with all submodules), runs `hugo build`, and writes the generated HTML into `jupyterhub_volumes/web/obidoc/`. Caddy then serves these files directly — no special routing is needed.
+
+### First installation
+
+The documentation is built automatically on the first full start if `jupyterhub_volumes/web/obidoc/` is empty:
+
+```bash
+./start-jupyterhub.sh
+```
+
+To force a build even if the directory is already populated, use `--build-obidoc` during a full start:
+
+```bash
+./start-jupyterhub.sh --build-obidoc
+```
+
+### Updating the documentation
+
+To rebuild the documentation without stopping the running stack:
+
+```bash
+./start-jupyterhub.sh --update-obidoc
+```
+
+This pulls the latest version of the builder image (or uses the local one with `--local-build`), reclones the `obitools4-doc` repository, rebuilds the site, and replaces the contents of `jupyterhub_volumes/web/obidoc/`. The JupyterHub stack keeps running throughout.
+
+### Removing the documentation
+
+To remove the built documentation (e.g. to free disk space or force a clean rebuild):
+
+```bash
+rm -rf jupyterhub_volumes/web/obidoc/*
+```
+
+The next `./start-jupyterhub.sh` will rebuild it automatically.
+
 ## Managing course and student data
 
 Each student lands in `/home/jovyan/work/` with three areas:

obijupyterhub/Dockerfile.builder

@@ -33,6 +33,7 @@ RUN apt-get update \
        libtiff5-dev \
        libjpeg-dev \
        libuv1-dev \
+       golang-go \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
@@ -44,7 +45,7 @@ RUN mkdir -p ${R_LIBS_BUILDER} \
 
 # Install Hugo (extended version for SCSS support)
 # Detect architecture and download appropriate binary
-ARG HUGO_VERSION=0.140.2
+ARG HUGO_VERSION=0.159.2
 RUN ARCH=$(dpkg --print-architecture) \
     && case "$ARCH" in \
          amd64) HUGO_ARCH="amd64" ;; \

start-jupyterhub.sh

@@ -38,6 +38,7 @@ REBUILD_HUB=false
 # Actions
 STOP_SERVER=false
 UPDATE_LECTURES=false
+UPDATE_OBIDOC=false
 BUILD_OBIDOC=false
 
 usage() {
@@ -58,7 +59,8 @@ Build options (--local-build only):
 Actions:
   --stop-server            Stop the stack and remove student containers, then exit
   --update-lectures        Rebuild the course website only (no Docker stop/start)
-  --build-obidoc           Force rebuild of obidoc documentation
+  --update-obidoc          Rebuild the obidoc documentation only (no Docker stop/start)
+  --build-obidoc           Force rebuild of obidoc documentation on next full start
   -h, --help               Show this help
 EOF
 }
@@ -76,6 +78,7 @@ while [[ $# -gt 0 ]]; do
         --rebuild-hub)         REBUILD_HUB=true; LOCAL_BUILD=true ;;
         --stop-server)         STOP_SERVER=true ;;
         --update-lectures)     UPDATE_LECTURES=true ;;
+        --update-obidoc)       UPDATE_OBIDOC=true ;;
         --build-obidoc)        BUILD_OBIDOC=true ;;
         -h|--help) usage; exit 0 ;;
         *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
@@ -263,17 +266,15 @@ publish_images() {
     version=$(read_version)
 
     # docker buildx --push uses Docker's own credential store, independent of
-    # skopeo. Verify auth early to get a clear error before a long build.
+    # skopeo. Prompt once before the (long) build so the user isn't surprised
-    echo -e "${BLUE}Checking registry authentication...${NC}"
+    # by an auth failure at the very end.
     local registry_host="${REGISTRY%%/*}"
-    if ! docker login "$registry_host" >/dev/null 2>&1; then
+    echo -e "${BLUE}Authenticating to ${registry_host} (required to push)...${NC}"
-        echo -e "${YELLOW}Not logged in to ${registry_host}. Running docker login...${NC}"
+    docker login "$registry_host" || {
-        docker login "$registry_host" || {
+        echo "Error: authentication to ${registry_host} failed." >&2
-            echo "Error: authentication to ${registry_host} failed." >&2
+        echo "Run: docker login ${registry_host}" >&2
-            echo "Run: docker login ${registry_host}" >&2
+        exit 1
-            exit 1
+    }
-        }
-    fi
 
     echo ""
     echo -e "${BLUE}Publishing images (version ${version}) to ${REGISTRY}${NC}"
@@ -387,7 +388,7 @@ build_obidoc() {
               -j 8 \
               https://github.com/metabarcoding/obitools4-doc.git
         cd obitools4-doc
-        hugo -D build --baseURL "/obidoc/"
+        hugo --gc --minify --buildDrafts --baseURL "/obidoc/"
         mkdir -p /workspace/jupyterhub_volumes/web/obidoc
         rm -rf /workspace/jupyterhub_volumes/web/obidoc/*
         mv public/* /workspace/jupyterhub_volumes/web/obidoc/
@@ -498,6 +499,19 @@ if $UPDATE_LECTURES; then
     exit 0
 fi
 
+if $UPDATE_OBIDOC; then
+    if $LOCAL_BUILD; then
+        build_builder_image
+    elif ! $NO_BUILD; then
+        docker pull "$BUILDER_IMAGE" 2>/dev/null \
+            || echo -e "${YELLOW}Could not pull builder image, using local cache.${NC}"
+    fi
+    BUILD_OBIDOC=true
+    build_obidoc
+    popd >/dev/null
+    exit 0
+fi
+
 stop_stack
 
 if $PUBLISH; then

web_src/_quarto.yml

@@ -4,6 +4,9 @@ project:
   post-render:
     - scripts/copy-to-web.sh
 
+execute:
+  freeze: auto
+
 format:
   html:
     toc: false