This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr-mcp.git
The following commit(s) were added to refs/heads/main by this push:
new 47a9289f docs: set the OTLP URLs in every HTTP-mode docker run (#262)
47a9289f is described below
commit 47a9289fd4a7f5447aacfa2956ad9fec506d5dc0
Author: Aditya Parikh <[email protected]>
AuthorDate: Mon Oct 26 15:31:33 2026 -0400
docs: set the OTLP URLs in every HTTP-mode docker run (#262)
The OTLP endpoints default to localhost:4318, which suits java -jar and
bootRun next to the lgtm container. Inside a container, localhost is
the container itself, so every documented HTTP-mode docker run exported
nowhere and logged a connection error on each attempt.
Each HTTP-mode docker run now sets OTEL_TRACES_URL, OTEL_METRICS_URL and
OTEL_LOGS_URL to host.docker.internal:4318. The Compose and Kubernetes
examples point them at a collector host. The observability guide
explains the Docker case, including the Linux steps: --add-host, and
OTLP_BIND=0.0.0.0, since compose.yaml publishes 4318 on loopback only.
Signed-off-by: Aditya Parikh <[email protected]>
Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
---
AGENTS.md | 6 ++++++
dev-docs/DEPLOYMENT.md | 20 +++++++++++++++++
dev-docs/graalvm-native-image.md | 3 +++
docs/clients/chatgpt.md | 3 +++
docs/clients/claude-desktop.md | 3 +++
docs/clients/codex.md | 3 +++
docs/clients/mcp-inspector.md | 3 +++
docs/observability.md | 25 ++++++++++++++++++----
docs/site/content/pages/mcp/clients/claude-code.md | 3 +++
.../content/pages/mcp/clients/claude-desktop.md | 3 +++
docs/site/content/pages/mcp/clients/cursor.md | 3 +++
docs/site/content/pages/mcp/clients/jetbrains.md | 3 +++
.../content/pages/mcp/clients/mcp-inspector.md | 3 +++
docs/site/content/pages/mcp/clients/vs-code.md | 3 +++
docs/site/content/pages/mcp/observability.md | 25 ++++++++++++++++++----
docs/site/content/pages/mcp/security.md | 3 +++
16 files changed, 104 insertions(+), 8 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 4b3b3271..72abf222 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -94,10 +94,16 @@ docker run -i --rm -e
SOLR_URL=http://host.docker.internal:8983/solr/ solr-mcp:l
# HTTP — Jib JVM
docker run -p 8080:8080 --rm -e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ solr-mcp:latest
# HTTP — native
docker run -p 8080:8080 --rm -e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/
solr-mcp:latest-native-http
```
diff --git a/dev-docs/DEPLOYMENT.md b/dev-docs/DEPLOYMENT.md
index 09d16b60..60f79dac 100644
--- a/dev-docs/DEPLOYMENT.md
+++ b/dev-docs/DEPLOYMENT.md
@@ -85,12 +85,18 @@ docker run -i --rm \
# HTTP — Jib JVM
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
# HTTP — native
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest-native-http
```
@@ -153,6 +159,9 @@ docker run -i --rm \
```bash
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://your-collector-host:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://your-collector-host:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://your-collector-host:4318/v1/logs \
-e SOLR_URL=http://your-solr-host:8983/solr/ \
solr-mcp:1.0.0-SNAPSHOT
```
@@ -328,6 +337,10 @@ services:
environment:
- SOLR_URL=http://solr:8983/solr/
- PROFILES=http
+ # OTLP export; inside the container, the localhost:4318 default is the
container itself
+ - OTEL_TRACES_URL=http://your-collector-host:4318/v1/traces
+ - OTEL_METRICS_URL=http://your-collector-host:4318/v1/metrics
+ - OTEL_LOGS_URL=http://your-collector-host:4318/v1/logs
ports:
- "8080:8080"
depends_on:
@@ -364,6 +377,13 @@ spec:
value: "http://solr-service:8983/solr/";
- name: PROFILES
value: "http"
+ # OTLP export; inside the pod, the localhost:4318 default is the pod
itself
+ - name: OTEL_TRACES_URL
+ value: "http://otel-collector:4318/v1/traces";
+ - name: OTEL_METRICS_URL
+ value: "http://otel-collector:4318/v1/metrics";
+ - name: OTEL_LOGS_URL
+ value: "http://otel-collector:4318/v1/logs";
ports:
- containerPort: 8080
---
diff --git a/dev-docs/graalvm-native-image.md b/dev-docs/graalvm-native-image.md
index 9bcbbb49..de0b7b37 100644
--- a/dev-docs/graalvm-native-image.md
+++ b/dev-docs/graalvm-native-image.md
@@ -257,6 +257,9 @@ never enter its closed world.
docker run -i --rm \
-e SOLR_URL=http://host.docker.internal:8983/solr/
solr-mcp:latest-native-stdio
docker run -p 8080:8080 --rm -e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/
solr-mcp:latest-native-http
```
diff --git a/docs/clients/chatgpt.md b/docs/clients/chatgpt.md
index b8dc6f83..9122d829 100644
--- a/docs/clients/chatgpt.md
+++ b/docs/clients/chatgpt.md
@@ -22,6 +22,9 @@ PROFILES=http HTTP_SECURITY_ENABLED=false
SOLR_URL=http://localhost:8983/solr/ \
# Docker (local image — build first with ./gradlew jibDockerBuild)
docker run -p 8080:8080 --rm \
-e PROFILES=http -e HTTP_SECURITY_ENABLED=false \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
```
diff --git a/docs/clients/claude-desktop.md b/docs/clients/claude-desktop.md
index a7a526d2..3ab938b5 100644
--- a/docs/clients/claude-desktop.md
+++ b/docs/clients/claude-desktop.md
@@ -72,6 +72,9 @@ PROFILES=http ./gradlew bootRun
# Or Docker (local image)
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
```
diff --git a/docs/clients/codex.md b/docs/clients/codex.md
index 517750e7..78fb8ccf 100644
--- a/docs/clients/codex.md
+++ b/docs/clients/codex.md
@@ -83,6 +83,9 @@ PROFILES=http HTTP_SECURITY_ENABLED=false
SOLR_URL=http://localhost:8983/solr/ \
# Docker (local image)
docker run -p 8080:8080 --rm \
-e PROFILES=http -e HTTP_SECURITY_ENABLED=false \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
```
diff --git a/docs/clients/mcp-inspector.md b/docs/clients/mcp-inspector.md
index f2ab105c..dda4fca9 100644
--- a/docs/clients/mcp-inspector.md
+++ b/docs/clients/mcp-inspector.md
@@ -34,6 +34,9 @@ This starts the Inspector UI at `http://localhost:6274`.
# Or Docker (local image — build first with ./gradlew jibDockerBuild)
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
diff --git a/docs/observability.md b/docs/observability.md
index 52bbdf7b..f3b70c74 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -78,10 +78,27 @@
management.opentelemetry.logging.export.otlp.endpoint=${OTEL_LOGS_URL:http://loc
Export goes over **OTLP/HTTP on port 4318**, with a separate full URL per
signal.
Each endpoint is a complete path ending in `/v1/traces`, `/v1/metrics` or
`/v1/logs` — not a base address.
-When the server runs in a container and LGTM on the host, `localhost` is the
container
-itself; point all three variables at the host, e.g.
-`OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces` (plus
-`--add-host=host.docker.internal:host-gateway` on Linux).
+The `localhost` defaults suit `java -jar` and `bootRun` next to the `lgtm`
container.
+**In Docker they do not**: inside a container, `localhost` is the container
itself, so set
+all three URLs to wherever the collector is reachable from the container. With
LGTM on the
+host:
+
+```bash
+docker run -p 8080:8080 --rm \
+ -e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+On Linux, also add `--add-host=host.docker.internal:host-gateway`, and start
LGTM with
+`OTLP_BIND=0.0.0.0 docker compose up -d lgtm`: by default `compose.yaml`
publishes port
+4318 on the loopback interface only, which a container cannot reach. If the
server and the
+collector share a Docker network, use the collector's container name instead,
e.g.
+`http://lgtm:4318/v1/traces`. Until a collector answers on those URLs, the
server logs a
+connection error on each export attempt.
### Generate Some Activity ###
diff --git a/docs/site/content/pages/mcp/clients/claude-code.md
b/docs/site/content/pages/mcp/clients/claude-code.md
index ceb84baf..87486701 100644
--- a/docs/site/content/pages/mcp/clients/claude-code.md
+++ b/docs/site/content/pages/mcp/clients/claude-code.md
@@ -100,6 +100,9 @@ PROFILES=http ./gradlew bootRun
# Or Docker (local image — build first with ./gradlew jibDockerBuild)
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
```
diff --git a/docs/site/content/pages/mcp/clients/claude-desktop.md
b/docs/site/content/pages/mcp/clients/claude-desktop.md
index 432680c3..58b16530 100644
--- a/docs/site/content/pages/mcp/clients/claude-desktop.md
+++ b/docs/site/content/pages/mcp/clients/claude-desktop.md
@@ -75,6 +75,9 @@ PROFILES=http ./gradlew bootRun
# Or Docker (local image — build first with ./gradlew jibDockerBuild)
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
```
diff --git a/docs/site/content/pages/mcp/clients/cursor.md
b/docs/site/content/pages/mcp/clients/cursor.md
index cd737408..a49dd7c8 100644
--- a/docs/site/content/pages/mcp/clients/cursor.md
+++ b/docs/site/content/pages/mcp/clients/cursor.md
@@ -70,6 +70,9 @@ PROFILES=http ./gradlew bootRun
# Or Docker (local image — build first with ./gradlew jibDockerBuild)
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
```
diff --git a/docs/site/content/pages/mcp/clients/jetbrains.md
b/docs/site/content/pages/mcp/clients/jetbrains.md
index 5f6de9d7..af250f11 100644
--- a/docs/site/content/pages/mcp/clients/jetbrains.md
+++ b/docs/site/content/pages/mcp/clients/jetbrains.md
@@ -71,6 +71,9 @@ PROFILES=http ./gradlew bootRun
# Or Docker (local image — build first with ./gradlew jibDockerBuild)
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
```
diff --git a/docs/site/content/pages/mcp/clients/mcp-inspector.md
b/docs/site/content/pages/mcp/clients/mcp-inspector.md
index e6024a84..5d5516ab 100644
--- a/docs/site/content/pages/mcp/clients/mcp-inspector.md
+++ b/docs/site/content/pages/mcp/clients/mcp-inspector.md
@@ -48,6 +48,9 @@ This starts the Inspector UI at `http://localhost:6274`.
# Or Docker (local image — build first with ./gradlew jibDockerBuild)
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
diff --git a/docs/site/content/pages/mcp/clients/vs-code.md
b/docs/site/content/pages/mcp/clients/vs-code.md
index 888c7503..a285918c 100644
--- a/docs/site/content/pages/mcp/clients/vs-code.md
+++ b/docs/site/content/pages/mcp/clients/vs-code.md
@@ -81,6 +81,9 @@ PROFILES=http ./gradlew bootRun
# Or Docker (local image — build first with ./gradlew jibDockerBuild)
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
```
diff --git a/docs/site/content/pages/mcp/observability.md
b/docs/site/content/pages/mcp/observability.md
index c18365f2..c0bb1973 100644
--- a/docs/site/content/pages/mcp/observability.md
+++ b/docs/site/content/pages/mcp/observability.md
@@ -81,10 +81,27 @@
management.opentelemetry.logging.export.otlp.endpoint=${OTEL_LOGS_URL:http://loc
Export goes over **OTLP/HTTP on port 4318**, with a separate full URL per
signal.
Each endpoint is a complete path ending in `/v1/traces`, `/v1/metrics` or
`/v1/logs` — not a base address.
-When the server runs in a container and LGTM on the host, `localhost` is the
container
-itself; point all three variables at the host, e.g.
-`OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces` (plus
-`--add-host=host.docker.internal:host-gateway` on Linux).
+The `localhost` defaults suit `java -jar` and `bootRun` next to the `lgtm`
container.
+**In Docker they do not**: inside a container, `localhost` is the container
itself, so set
+all three URLs to wherever the collector is reachable from the container. With
LGTM on the
+host:
+
+```bash
+docker run -p 8080:8080 --rm \
+ -e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+On Linux, also add `--add-host=host.docker.internal:host-gateway`, and start
LGTM with
+`OTLP_BIND=0.0.0.0 docker compose up -d lgtm`: by default `compose.yaml`
publishes port
+4318 on the loopback interface only, which a container cannot reach. If the
server and the
+collector share a Docker network, use the collector's container name instead,
e.g.
+`http://lgtm:4318/v1/traces`. Until a collector answers on those URLs, the
server logs a
+connection error on each export attempt.
### Generate Some Activity ###
diff --git a/docs/site/content/pages/mcp/security.md
b/docs/site/content/pages/mcp/security.md
index 18876f09..75c8e74c 100644
--- a/docs/site/content/pages/mcp/security.md
+++ b/docs/site/content/pages/mcp/security.md
@@ -27,6 +27,9 @@ Or with Docker (local image — build first with
`./gradlew jibDockerBuild`)
```bash
docker run -p 8080:8080 --rm \
-e PROFILES=http \
+ -e OTEL_TRACES_URL=http://host.docker.internal:4318/v1/traces \
+ -e OTEL_METRICS_URL=http://host.docker.internal:4318/v1/metrics \
+ -e OTEL_LOGS_URL=http://host.docker.internal:4318/v1/logs \
-e OAUTH2_ISSUER_URI=https://your-provider.example.com/ \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:latest
