From 36191a5f7bca510b081f7c670dd91f6f9ef669ac Mon Sep 17 00:00:00 2001 From: Raul Bardaji Date: Wed, 10 Jun 2026 08:26:25 -0600 Subject: [PATCH] docs: add local/IP deployment guide and clarify http vs https in examples Several first-run failures share one root cause: the docs and demo slides implicitly assume a real domain with TLS, so evaluators deploying on a bare IP without a certificate hit avoidable errors (e.g. https:// failing, which surfaces downstream as a confusing "Kafka endpoint undefined"). Add a "Local / IP-based deployment (no domain, no TLS)" section to the README covering http vs https, host IP vs internal overlay addresses, ports, profiles without Pelican, rebuilding after updates, and the Kafka reachability caveat (KAFKA_HOST/KAFKA_PORT are returned to clients verbatim, so they must be externally reachable). Also note in the Python automation guide and the demo presentation that the https examples assume a domain+cert and a bare IP should use http. Closes #191 --- CHANGELOG.md | 11 ++++++ README.md | 35 +++++++++++++++++++ api/config/swagger_settings.py | 2 +- docs/demo/NDP-demo-presentation.md | 1 + .../04-automating-with-python.md | 6 ++++ 5 files changed, 54 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 62a437c..e181c39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.32.4] - 2026-06-05 + +### Added +- **README: "Local / IP-based deployment (no domain, no TLS)" section.** Consolidates the rules for evaluating the Endpoint on a bare IP/`localhost` without a domain or certificate: use `http://` not `https://`, use the host's real IP (not internal overlay/pod addresses), the correct ports, profiles without Pelican, rebuilding after updates, and the Kafka/streaming reachability caveat (the Endpoint returns the configured `KAFKA_HOST`/`KAFKA_PORT` verbatim, so clients outside the Docker network need externally reachable values, not internal names like `kafka:9093`). + +### Changed +- **Python client and demo-slide examples clarify `http` vs `https`.** The `https://…` `base_url` examples in the automation guide and the demo presentation now note that `https` assumes a real domain with a TLS certificate, and that a bare IP/`localhost` deployment should use `http://`. + +### Backwards compatibility +- Documentation only. No API behavior, request/response shapes, or routes change. + ## [0.32.3] - 2026-06-05 ### Fixed diff --git a/README.md b/README.md index fe83d11..70689e9 100644 --- a/README.md +++ b/README.md @@ -366,6 +366,41 @@ PRE_CKAN_API_KEY=your-ndp-preckan-api-key PRE_CKAN_ORGANIZATION=ep-your-assigned-org-id ``` +### 6. Local / IP-based deployment (no domain, no TLS) + +If you are evaluating the Endpoint on a plain VM or workstation reached by its +**IP address** (or `localhost`) and you do **not** have a domain name or a TLS +certificate, follow these rules — most first-run problems come from assuming a +domain/HTTPS setup that isn't there: + +- **Use `http://`, not `https://`.** A bare IP address cannot present a valid + TLS certificate, so `https://` fails. This applies to the browser URLs + **and** to the `base_url`/`API_URL` you pass to the Python client, the + streaming client, etc. The `https://my-endpoint…` examples elsewhere in the + docs and slides assume a real domain with a certificate. +- **Use the host's real IP or `localhost`** — not an internal overlay/pod + address (e.g. `10.244.x.x`), which is not reachable from your machine. +- **Pick the right port.** `docker run -p 8001:80` → `http://:8001`; + `docker compose` publishes the API on host port **8002** by default → + `http://:8002`. The container always serves on port 80 internally. +- **Start only the profiles you need** (e.g. `--profile mongodb --profile s3`). + Avoid `--profile full` / `--profile pelican`: the Pelican services need extra + TLS/federation setup and will restart-loop on a fresh machine. +- **Rebuild after updating code** (`docker compose build --no-cache api`, or + `docker pull rbardaji/ndp-ep-api:latest`) — `docker compose up` reuses the + old image otherwise. +- **Kafka / streaming reachability.** The Endpoint hands streaming clients the + `KAFKA_HOST`/`KAFKA_PORT` you configured, **verbatim** (via + `GET /status/kafka-details`). If your client runs **outside** the Docker + network (for example, a notebook on your laptop), those values must be the + **externally reachable** address — the host's IP/hostname and the + externally-published Kafka port — **not** an internal Docker service name + (`kafka`) or an internal-only port. Internal names like `kafka:9093` only + resolve between containers on the same Docker network. + +Verify with the `http://` URLs from [Verify Installation](#4-verify-installation) +(`/docs`, `/ui/`, `/health`). + ## 🔒 Group-Based Access Control The API supports optional group-based access control to restrict write operations (POST, PUT, DELETE) to users belonging to specific groups. diff --git a/api/config/swagger_settings.py b/api/config/swagger_settings.py index c58fd64..e605c2a 100644 --- a/api/config/swagger_settings.py +++ b/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.3" + swagger_version: str = "0.32.4" root_path: str = "" # API root path prefix (e.g., "/test" or "") is_public: bool = True metrics_endpoint: str = "https://federation.ndp.utah.edu/metrics/" diff --git a/docs/demo/NDP-demo-presentation.md b/docs/demo/NDP-demo-presentation.md index d428456..76bdeaf 100644 --- a/docs/demo/NDP-demo-presentation.md +++ b/docs/demo/NDP-demo-presentation.md @@ -729,6 +729,7 @@ pip install ndp-ep from ndp_ep import APIClient # 1. Connect to the Endpoint with your token +# (https assumes a real domain + TLS cert; on a bare IP/localhost use http://) client = APIClient(base_url="https://my-endpoint/ep-api", token="…") # 2. List organizations diff --git a/docs/info_for_nationaldataplatform/04-automating-with-python.md b/docs/info_for_nationaldataplatform/04-automating-with-python.md index 187b1fe..13f6fba 100644 --- a/docs/info_for_nationaldataplatform/04-automating-with-python.md +++ b/docs/info_for_nationaldataplatform/04-automating-with-python.md @@ -41,6 +41,12 @@ client.get_token(username="me@my-institution.edu", password="…") client honours the Endpoint's role checks — what your token can do from code is exactly what your account can do from the web. +> **`http` vs `https`:** the `https://…` examples above assume the Endpoint is +> served on a real domain with a valid TLS certificate. If you reach it by a +> bare **IP address** (or `localhost`) without a certificate, use `http://` +> instead (e.g. `base_url="http://:8002"`) — `https://` will fail +> because an IP cannot present a valid certificate. + ## Common operations ```python