Fix ROOT_PATH-aware health check and improve local deployment docs

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.32.1] - 2026-06-04
+
+### Fixed
+- **The container health check no longer reports `unhealthy` when `ROOT_PATH` is set.** The check was hardcoded to `http://localhost/health` (through nginx), but when `ROOT_PATH` is configured nginx serves the API under `${ROOT_PATH}/`, so that path returned `404` and the container stayed permanently `unhealthy` even though the API was working. Both the `docker-compose.yml` and `Dockerfile.allinone` health checks now probe uvicorn directly at `http://localhost:8000/health`, which is independent of nginx and of `ROOT_PATH`.
+- **`example.env` no longer ships a broken `METRICS_ENDPOINT` value.** The placeholder text `NDP_FEDERATION_METRICS_ENDPOINT default to federation/test` is replaced with the real default collector URL, so copying `example.env` verbatim yields a working configuration.
+
+### Changed
+- **Quick Start documentation steers new deployments away from `--profile full`.** The README now recommends starting only the profiles you need and documents that the `full`/`pelican` profiles start the Pelican federation services, which require additional TLS/federation setup and will restart-loop on a fresh local machine. This prevents a working installation from looking broken.
+- **`example.env` clarifies the CKAN fields when using the MongoDB backend.** `CKAN_URL`/`CKAN_API_KEY` should stay empty with `LOCAL_CATALOG_BACKEND=mongodb`, and the note explains that `CKAN_LOCAL_ENABLED` is the master switch for local catalog writes for any backend, not a "use CKAN" flag.
+- **README documents how to update to a new version.** Added a note that `docker compose up` reuses a previously built image and must be rebuilt (`build --no-cache` / `up -d --build`) after pulling new code, plus how to confirm the running version (and how to spot a stale pre-nginx image from the `docker ps` `COMMAND` column).
+
+### Backwards compatibility
+- Documentation and example-configuration only. No API behavior, request/response shapes, or routes change.
+
 ## [0.32.0] - 2026-05-31
 
 ### Added

Dockerfile.allinone

@@ -81,8 +81,11 @@ RUN mkdir -p /var/log/supervisor /var/log/nginx
 EXPOSE 80
 
 # Health check
+# Probe uvicorn directly on :8000 so the check is independent of nginx and of
+# ROOT_PATH (nginx serves the API under ${ROOT_PATH}/, but the uvicorn /health
+# route is always at /health regardless of root_path).
 HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=40s \
-    CMD curl -f http://localhost/health || exit 1
+    CMD curl -f http://localhost:8000/health || exit 1
 
 # Copy entrypoint script
 COPY entrypoint.sh /app/entrypoint.sh

README.md

@@ -261,9 +261,9 @@ The `docker-compose.yml` uses **profiles** to let you choose which services to s
 | `kafka` | Kafka + Zookeeper + Kafka UI |
 | `s3` | MinIO (S3-compatible storage) |
 | `jupyter` | JupyterLab |
-| `pelican` | Pelican Federation (Registry, Director, Origin, Cache) |
+| `pelican` | Pelican Federation (Registry, Director, Origin, Cache) — needs extra setup, see warning below |
 | `frontend` | NDP-EP Frontend Web UI |
-| `full` | All services |
+| `full` | All services (includes Pelican — see warning below) |
 
 **Usage Examples:**
 
@@ -277,12 +277,29 @@ docker compose --profile mongodb up
 # API + MongoDB + Kafka
 docker compose --profile mongodb --profile kafka up
 
-# API + all services
-docker compose --profile full up
+# Recommended local stack: catalog + storage + streaming + notebooks (no Pelican)
+docker compose --profile mongodb --profile s3 --profile kafka --profile jupyter up
 ```
 
+**Recommended for most deployments:** start only the profiles you actually need (e.g. `--profile mongodb --profile s3`). This keeps the stack lean and avoids services that require extra setup.
+
+> ⚠️ **About `--profile full` and `--profile pelican`:** the `full` profile also starts the Pelican federation services (registry, director, origin, cache). Those require additional TLS/federation configuration that is **not** included out of the box, so on a fresh local machine they will enter a **restart loop**. This is expected and does not mean the rest of the stack is broken — Pelican is **not needed** for a typical deployment. Only enable the `pelican` profile once you have completed the Pelican federation setup.
+
 **Note:** When using external services (e.g., your own CKAN or Kafka), just run `docker compose up` and configure the external URLs in your `.env` file.
 
+> 🔄 **Updating to a new version:** `docker compose up` reuses an already-built
+> image and will **not** pick up new code on its own. After `git pull` (or any
+> change to the source), rebuild the image explicitly, otherwise you keep running
+> the old one:
+> ```bash
+> docker compose build --no-cache api
+> docker compose up -d            # or: docker compose up -d --build
+> ```
+> To confirm which version is actually running, check the `version` field at
+> `http://localhost:<port>/docs` (or in the metrics line of `docker logs ndp-ep-api`).
+> If the `COMMAND` column of `docker ps` for `ndp-ep-api` shows `uvicorn …` instead
+> of `/app/entrypoint.sh`, you are on a stale pre-nginx image and need to rebuild.
+
 ### 4. Verify Installation
 
 Once the container is running, verify everything is working:

api/config/swagger_settings.py

@@ -12,7 +12,7 @@ class Settings(BaseSettings):
 
     swagger_title: str = "API Documentation"
     swagger_description: str = "This is the API documentation."
-    swagger_version: str = "0.32.0"
+    swagger_version: str = "0.32.1"
     root_path: str = ""  # API root path prefix (e.g., "/test" or "")
     is_public: bool = True
     metrics_endpoint: str = "https://federation.ndp.utah.edu/metrics/"

docker-compose.yml

@@ -17,7 +17,10 @@ services:
       - ndp-network
     restart: unless-stopped
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost/health"]
+      # Probe uvicorn directly on :8000 so the check is independent of nginx
+      # and of ROOT_PATH (nginx serves the API under ${ROOT_PATH}/, but the
+      # uvicorn /health route is always at /health regardless of root_path).
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
       interval: 30s
       timeout: 10s
       retries: 3

example.env

@@ -20,7 +20,10 @@ EP_NAME="EP-DEMO"
 
 # Interval in seconds for sending metrics (default: 3300 seconds = 55 minutes)
 METRICS_INTERVAL_SECONDS=3300
-METRICS_ENDPOINT=NDP_FEDERATION_METRICS_ENDPOINT default to federation/test
+
+# Endpoint the periodic metrics report is POSTed to.
+# Leave the default unless the NDP team gives you a different collector URL.
+METRICS_ENDPOINT=https://federation.ndp.utah.edu/metrics/
 # ==============================================
 # ACCESS CONTROL (Optional)
 # ==============================================
@@ -84,6 +87,10 @@ CKAN_LOCAL_ENABLED=True
 # ==============================================
 # CKAN-SPECIFIC CONFIGURATION (only if LOCAL_CATALOG_BACKEND=ckan)
 # ==============================================
+# Leave the two fields below EMPTY when LOCAL_CATALOG_BACKEND=mongodb — they
+# are only read by the CKAN backend. Note that CKAN_LOCAL_ENABLED above is the
+# master switch for local catalog writes for ANY backend, so it stays True even
+# on MongoDB; it is not a "use CKAN" flag despite the name.
 
 # Base URL of your local CKAN instance (Required only for CKAN backend)
 CKAN_URL=