Skip to content

Fix ROOT_PATH-aware health check and improve local deployment docs#186

Merged
rbardaji merged 2 commits into
mainfrom
docs/185-improve-local-deployment-docs
Jun 5, 2026
Merged

Fix ROOT_PATH-aware health check and improve local deployment docs#186
rbardaji merged 2 commits into
mainfrom
docs/185-improve-local-deployment-docs

Conversation

@rbardaji

@rbardaji rbardaji commented Jun 4, 2026

Copy link
Copy Markdown
Collaborator

Closes #185

Summary

Onboarding a new deployer surfaced one real bug and several documentation gaps that made a working installation look broken. This PR fixes all of them.

The health check bug (most impactful)

The container health check was hardcoded to http://localhost/health, which goes through nginx. When ROOT_PATH is set (e.g. /ep-api), nginx serves the API under ${ROOT_PATH}/, so http://localhost/health returns 404 and the container is reported unhealthy indefinitely even though the API is fully functional.

Verified on a live container running with ROOT_PATH=/ep-api:

  • localhost/health (via nginx, what the check used) → 404
  • localhost:8000/health (uvicorn directly) → 200

Both health checks now probe uvicorn directly at http://localhost:8000/health, which is independent of nginx and ROOT_PATH and correctly reflects API liveness:

  • docker-compose.yml
  • Dockerfile.allinone

Documentation fixes

  • example.env: replace the broken METRICS_ENDPOINT placeholder (NDP_FEDERATION_METRICS_ENDPOINT default to federation/test) with the real default collector URL, so copying the file verbatim yields a valid config.
  • example.env: clarify that CKAN_URL / CKAN_API_KEY stay empty on the MongoDB backend, and that CKAN_LOCAL_ENABLED is the master "allow local catalog writes" switch for any backend — not a "use CKAN" flag.
  • README.md: recommend starting only the profiles you need, and warn that the pelican / full profiles start the Pelican federation services, which need extra TLS/federation setup and will restart-loop on a fresh local machine. Added a "recommended local stack" example that excludes Pelican.

Version

Bumped to 0.32.1 (swagger_settings.py + CHANGELOG.md).

Testing

  • Confirmed on the live container (with ROOT_PATH=/ep-api) that the new health-check command curl -f http://localhost:8000/health returns HTTP 200 / exit 0, while the old http://localhost/health returned 404.
  • Changes are documentation + container configuration only; no API code paths change beyond the version string (existing tests mock the version, so none are affected).

Raul Bardaji added 2 commits June 4, 2026 14:01
…oy docs

The container health check was hardcoded to http://localhost/health through
nginx. When ROOT_PATH is set, nginx serves the API under ${ROOT_PATH}/, so
that path returned 404 and the container stayed unhealthy even though the API
worked. Both the docker-compose.yml and Dockerfile.allinone health checks now
probe uvicorn directly at http://localhost:8000/health, independent of nginx
and ROOT_PATH.

Also fix onboarding documentation: replace the broken METRICS_ENDPOINT
placeholder in example.env with the real default URL, clarify that CKAN_URL/
CKAN_API_KEY stay empty on the MongoDB backend, and steer the README away from
--profile full toward targeted profiles, warning that the pelican/full
profiles need extra setup and will restart-loop on a fresh machine.

Closes #185
After pulling new code, `docker compose up` reuses the previously built image,
so users can unknowingly keep running an old version. Document the explicit
rebuild step and how to confirm the running version (and how to spot a stale
pre-nginx image from the docker ps COMMAND column).
@rbardaji rbardaji merged commit 0200a12 into main Jun 5, 2026
1 check passed
@rbardaji rbardaji deleted the docs/185-improve-local-deployment-docs branch June 5, 2026 12:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Local deployment docs lead new users into avoidable failures

1 participant