[marcleblanc2]

Problem

An audit of the Docker Compose deployment (deploy-sourcegraph-docker#1507) checked the self-hosted pages against the v8.2.0 source and a running deployment. These pages tell customers to set things Sourcegraph does not read, or give steps which fail:

• INDEXED_SEARCH_INDEXERS is not a variable. The frontend reads INDEXED_SEARCH_INDEXER.
• Nothing reads SYMBOLS_URL or AWS_STS_REGIONAL_ENDPOINTS.
• The gitserver shard example sets SRC_GIT_SERVERS on worker. Only the frontend services read it.
• The OpenTelemetry example uses the logging exporter, which the collector in the image rejects, and receivers without an address, which listen on localhost only, so no other container reaches them.
• The Docker Compose debug ports in the pprof table are those of the removed single-container image.
• The external database steps link the 3.37 branch and tell customers to edit the base file. They never mention the code insights database.
• The Caddyfile volume lines (//builtins/...) do not match the base file, and the link goes to the 3.14 branch.
• The "Disable a service" snippet fails: service "sourcegraph-frontend-internal" depends on undefined service "codeintel-db".
• The Git SSH step chmod -v -R 600 makes the directory unreadable, and the files must belong to the gitserver container's user (100:101).
• The collector does not expand '$JAEGER_HOST:4317', so it exports no spans. The image's jaeger.yaml also needs JAEGER_OTLP_GRPC_PORT. The googlecloud exporter rejects retry_on_failure.
• Grafana is not at localhost:3370 on Docker Compose: the base file publishes no Grafana port. The Compose authentication override has no services: key and sits inside the Helm block.

Solution

• Use the variable names the frontend reads, and drop the ones nothing reads
• OpenTelemetry example: debug exporter, receivers on 0.0.0.0
• pprof table: the ports the Compose services listen on
• External databases: list the CODEINSIGHTS_PG* variables; the Compose steps use an override file and link the external-databases and aws-rds-databases examples in deploy-sourcegraph-docker
• Caddyfile: the volume lines as they are in the base file, link to main
• Disable a service: mark the dependency as required: false on migrator and sourcegraph-frontend-internal
• Git SSH: chmod 700 the directory, chmod 600 the files, then chown them to 100:101
• Tracing: ${env:JAEGER_HOST}, name both variables jaeger.yaml reads, drop retry_on_failure, and say that your own Jaeger must serve its UI under /-/debug/jaeger (the bundled image ignores QUERY_BASE_PATH)
• Grafana: an override which publishes port 3370 on loopback, ssh -L in place of sshuttle for a remote server, and the authentication override in its own block under services:

Not in this pull request:

• The broken #operations link in pprof.mdx: fix/links: Fix broken links (50 moved pages) #1926
• The two external links in postgres.mdx which fix/links: Replace or remove dead external links #1999 changes
• '$JAEGER_HOST:4317' in self-hosted/deploy/kubernetes/index.mdx: not tested on Kubernetes

Test plan

• Each variable checked for a reader in the v8.2.0 source of sourcegraph/sourcegraph and the pinned sourcegraph/zoekt revision
• On Sourcegraph 8.2.0 with Docker Compose (base stack evidence, examples evidence):
  • The collector rejects the logging exporter and starts with debug; with no receiver address it listens on 127.0.0.1 only
  • The debug ports listen as in the table
  • Both database examples start a healthy deployment against external Postgres servers with TLS; gitserver, searcher, worker, and the code intel workers connect without PG* variables of their own
• Each snippet in the second commit, run on the same deployment (verification thread):
  • Disable a service: docker compose config -q and up -d exit 0, 24 containers running against a stand-in external database
  • Git SSH: after the three commands, ssh and git ls-remote from inside gitserver-0 authenticate with the key against a test SSH server
  • '${env:JAEGER_HOST}:4317' exports spans (68); '$JAEGER_HOST:4317' logs "Exporting failed"
  • jaeger.yaml with only JAEGER_HOST fails with invalid port ""; the googlecloud snippet passes validation without retry_on_failure
  • Grafana port override: http://localhost:3370/-/debug/grafana returns 200, and Docker binds 127.0.0.1:3370 only; the authentication override passes config -q under services:
• node dev/check-spelling.mjs --diff <(git diff -U0 origin/main): no issues
• pnpm run check links --check-anchors --check-self-links: no failure on a changed line (the pprof.mdx #operations failure is on main)
• Not tested: IAM authentication against real RDS; the Kubernetes column of the pprof table; a clone which Sourcegraph itself starts over SSH; JAEGER_SERVER_URL with a customer's own Jaeger

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sourcegraph-docs	Ready	Preview	Nov 13, 2026 10:46am UTC

[github-actions]

Open the Diff Tour for this PR in Sourcegraph

[github-actions]

Page	Before	After	Diff
/self-hosted/deploy/docker-compose/configuration	prod	preview	−9 +29
/self-hosted/deploy/without-service-discovery	prod	preview	−2 +1
/self-hosted/external-services/postgres	prod	preview	−21 +17
/self-hosted/http-https-configuration	prod	preview	−3 +3
/self-hosted/observability/metrics	prod	preview	−6 +18
/self-hosted/observability/opentelemetry	prod	preview	−8 +9
/self-hosted/pprof	prod	preview	−7 +7