@uknows/setup 0.0.0-stage → 0.1.0

package/lib/contract-docs.mjs

@@ -0,0 +1,1154 @@
+// GENERATED from src/docs/install.ts by tools/sync-contract.mjs. Do not edit.
+// Change the docs file, then run: node tools/sync-contract.mjs
+/*
+ * UKNOWS install content: the single source for the /docs page and for
+ * /llms.txt (built by tools/build-installation-docs.mjs).
+ *
+ * Keep this file data only. It has no imports, so the docs build can load it
+ * with a plain TypeScript transpile.
+ *
+ * Copy rules: plain simple English, one instruction per sentence, active
+ * voice, sentence case, digits for numbers, UKNOWS brand only, no em dashes.
+ */
+
+/**
+ * The site address and the ingest address are build settings. A test build
+ * sets VITE_UKNOWS_SITE_URL (for example https://uknows-test.example.com) and
+ * VITE_UKNOWS_INGEST_HOST (for example ingest-test.example.com). Without them,
+ * the production names below apply. Vite reads import.meta.env. The Node tools
+ * that build llms.txt and the setup CLI contract read process.env.
+ */
+export const DEFAULT_SITE_URL = 'https://uknows.defacloud.my'
+export const DEFAULT_INGEST_HOST = 'ingest.uknows.defacloud.my'
+
+// Written as import.meta.env exactly, so Vite and Vitest replace it. Node has no import.meta.env.
+export const BUILD_ENV = {}
+
+/** A build setting without spaces around it or a trailing slash, or the default. A bad value stops the build. */
+export function buildSetting(name, fallback, valid) {
+  const raw = BUILD_ENV[name]
+  const value = typeof raw === 'string' ? raw.trim().replace(/\/+$/, '') : ''
+  if (!value) return fallback
+  if (!valid.test(value)) throw new Error(`${name} is not a valid address: ${value}`)
+  return value
+}
+
+/** https with a host name, or http on this computer for a local test. No path. */
+export const SITE_URL = buildSetting('VITE_UKNOWS_SITE_URL', DEFAULT_SITE_URL, /^(?:https:\/\/[a-z0-9]([a-z0-9.-]*[a-z0-9])?|http:\/\/(?:localhost|127\.0\.0\.1))(?::\d{1,5})?$/i)
+/** A host name only, with an optional port. The apps always send over https. */
+export const INGEST_HOST = buildSetting('VITE_UKNOWS_INGEST_HOST', DEFAULT_INGEST_HOST, /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(?::\d{1,5})?$/i)
+export const DOCS_URL = `${SITE_URL}/docs`
+export const LLMS_URL = `${SITE_URL}/llms.txt`
+export const INGEST_ENDPOINT = `https://${INGEST_HOST}/otlp`
+/** The route that tells whether a key works. The site serves it, not the ingest host. */
+export const PING_URL = `${SITE_URL}/api/v1/ingest/ping`
+export const EXAMPLE_SERVICE = 'orders-api'
+
+/** The 5 plain settings. Commit them in the repo of each app. */
+export const SETTINGS = [
+  { name: 'OTEL_SERVICE_NAME', value: EXAMPLE_SERVICE, summary: 'The name of this app in UKNOWS. Use a different name for each app.' },
+  { name: 'OTEL_EXPORTER_OTLP_ENDPOINT', value: INGEST_ENDPOINT, summary: 'The UKNOWS address that gets your data.' },
+  { name: 'OTEL_EXPORTER_OTLP_PROTOCOL', value: 'http/protobuf', summary: 'Send data in the OTLP format over HTTPS.' },
+  { name: 'OTEL_METRICS_EXPORTER', value: 'none', summary: 'Send traces only.' },
+  { name: 'OTEL_LOGS_EXPORTER', value: 'none', summary: 'Send traces only. Your logs stay where they are now.' },
+]
+
+/** The 1 secret. Set it once for each environment on the platform, never in the repo. */
+export const SECRET = {
+  name: 'OTEL_EXPORTER_OTLP_HEADERS',
+  header: 'x-uknows-key',
+  placeholder: '<key>',
+  value: 'x-uknows-key=<key>',
+  summary: 'Set your key as a secret on your platform, once for each environment. Keep it out of your repo.',
+}
+
+export const SETTINGS_ENV = SETTINGS.map((setting) => `${setting.name}=${setting.value}`).join('\n')
+export const SECRET_ENV = `${SECRET.name}=${SECRET.value}`
+
+export function dockerEnv(extra = []) {
+  const pairs = [...SETTINGS.map((setting) => `${setting.name}=${setting.value}`), ...extra]
+  return `ENV ${pairs.join(' \\\n    ')}`
+}
+
+/** The ENV lines for the final stage of a Dockerfile. */
+export const SETTINGS_DOCKERFILE = dockerEnv()
+
+/**
+ * The 5 settings as an env file, for apps that do not run from a Dockerfile.
+ * It has no key, so it is safe to commit. SETTINGS_FILE_LOADERS shows how to
+ * load it.
+ */
+export const SETTINGS_FILE = {
+  path: 'otel.env',
+  language: 'sh',
+  summary: 'Use this file when your app does not start from a Dockerfile. It has no key, so it is safe to commit.',
+  content: SETTINGS_ENV,
+}
+
+/**
+ * The setup tool, npx @uknows/setup (packages/uknows-setup). A build with
+ * test addresses puts them in front of the command, so the test copy of the
+ * page gives a command that writes and checks the test addresses. Production
+ * gives the plain command.
+ */
+export const SETUP_ADDRESSES = [
+  ...(SITE_URL === DEFAULT_SITE_URL ? [] : [`UKNOWS_SITE_URL=${SITE_URL}`]),
+  ...(INGEST_HOST === DEFAULT_INGEST_HOST ? [] : [`UKNOWS_INGEST_ENDPOINT=${INGEST_ENDPOINT}`]),
+]
+const setupCommand = (args = '')         => [...SETUP_ADDRESSES, `npx @uknows/setup${args}`].join(' ')
+
+export const NETWORK = {
+  host: INGEST_HOST,
+  port: 443,
+  text: `Allow outbound HTTPS from your apps to ${INGEST_HOST} on port 443. Your apps send data to UKNOWS. UKNOWS never connects to your apps.`,
+}
+
+/** Extra steps that the page can show folded, under the title. */
+
+/** The upstream OpenTelemetry Java agent, pinned. Checksum from the release checksums.txt. */
+export const JAVA_AGENT = {
+  version: '2.32.0',
+  file: 'opentelemetry-javaagent.jar',
+  url: 'https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.32.0/opentelemetry-javaagent.jar',
+  sha256: 'f787eb6c7f3d18e69a431e108a15278d25ee37f83d68b678f621e063f3988f82',
+}
+
+export const NODE_REGISTER = '@opentelemetry/auto-instrumentations-node/register'
+/** For ES modules: the loader hook gives each request its route. No space after = so 1 value holds both options. */
+export const NODE_ESM_OPTIONS = `--experimental-loader=@opentelemetry/instrumentation/hook.mjs --import=${NODE_REGISTER}`
+
+/** .NET writes its own OpenTelemetry log files. The default folder is not writable on macOS or as a user that is not root. */
+export const DOTNET_LOG_DIRECTORY = 'OTEL_DOTNET_AUTO_LOG_DIRECTORY=/tmp/otel-dotnet'
+
+export const GO_INIT = `package main
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"strings"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/propagation"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// setupOTel sends traces to the address in the OTEL_ settings.
+// Call the returned function when the app stops. It sends the last data.
+func setupOTel(ctx context.Context) (func(context.Context) error, error) {
+	if os.Getenv("OTEL_SDK_DISABLED") == "true" {
+		return func(context.Context) error { return nil }, nil
+	}
+	exporter, err := otlptracehttp.New(ctx)
+	if err != nil {
+		return nil, err
+	}
+	provider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
+	otel.SetTracerProvider(provider)
+	otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{}, propagation.Baggage{},
+	))
+	return provider.Shutdown, nil
+}
+
+// withRoute adds the route of each request, such as /orders/{id}, to its
+// trace, after the net/http ServeMux picks the route. Without it, UKNOWS
+// shows all requests of the app as 1 endpoint.
+func withRoute(mux http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mux.ServeHTTP(w, r)
+		// r.Pattern is, for example, "GET /orders/{id}". The route starts at the first /.
+		if i := strings.IndexByte(r.Pattern, '/'); i >= 0 {
+			setRoute(r, r.Pattern[i:])
+		}
+	})
+}
+
+// setRoute adds a route to the trace of the request and names the trace
+// after it, for example GET /orders/{id}.
+func setRoute(r *http.Request, route string) {
+	if route != "" {
+		span := trace.SpanFromContext(r.Context())
+		span.SetName(r.Method + " " + route)
+		span.SetAttributes(attribute.String("http.route", route))
+	}
+}`
+
+export const GO_MAIN = `// Imports for this code: "context", "errors", "log", "net/http",
+// "os", "os/signal", "syscall" and "time".
+
+// 1. Start OpenTelemetry at the start of main.
+shutdown, err := setupOTel(context.Background())
+if err != nil {
+	log.Fatal(err)
+}
+
+// 2. Add the middleware for your router. Keep only the lines for your router.
+var handler http.Handler
+
+// net/http: wrap the ServeMux. withRoute is in otel.go.
+// import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
+handler = otelhttp.NewHandler(withRoute(mux), "http.server")
+
+// chi: add this middleware before your routes. Then wrap the router.
+// import "github.com/go-chi/chi/v5" and otelhttp
+router.Use(func(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		next.ServeHTTP(w, r)
+		setRoute(r, chi.RouteContext(r.Context()).RoutePattern())
+	})
+})
+handler = otelhttp.NewHandler(router, "http.server")
+
+// Gin: add the middleware. Then use the router as the handler.
+// import "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
+router.Use(otelgin.Middleware(os.Getenv("OTEL_SERVICE_NAME")))
+handler = router
+
+// Echo v4: add the middleware. Then use e as the handler.
+// import echootel "github.com/labstack/echo-otel/v4"
+e.Use(echootel.NewMiddleware(""))
+handler = e
+
+// 3. Run the server. On Ctrl+C or SIGTERM, stop the server.
+ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+defer stop()
+srv := &http.Server{Addr: ":8080", Handler: handler}
+serveErr := make(chan error, 1)
+go func() { serveErr <- srv.ListenAndServe() }()
+select {
+case err = <-serveErr:
+case <-ctx.Done():
+	stopCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	err = srv.Shutdown(stopCtx)
+	cancel()
+}
+
+// 4. Send the last data before the app exits.
+flushCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+_ = shutdown(flushCtx)
+cancel()
+if err != nil && !errors.Is(err, http.ErrServerClosed) {
+	log.Fatal(err)
+}`
+
+export const RUBY_INITIALIZER = `# UKNOWS monitoring. The OTEL_ settings configure it.
+unless ENV["OTEL_SDK_DISABLED"] == "true"
+  require "opentelemetry/sdk"
+  require "opentelemetry/exporter/otlp"
+  require "opentelemetry/instrumentation/all"
+
+  OpenTelemetry::SDK.configure do |c|
+    c.use_all
+  end
+end`
+
+/** Adds UKNOWS beside the exporters that a Collector has now. otlphttp adds /v1/traces to the endpoint. */
+export const COLLECTOR_CONFIG = [
+  'exporters:',
+  '  otlphttp/uknows:',
+  `    endpoint: ${INGEST_ENDPOINT}`,
+  '    headers:',
+  '      x-uknows-key: ${env:UKNOWS_KEY}',
+  '',
+  'service:',
+  '  pipelines:',
+  '    traces:',
+  '      # Keep your exporters. otlp/current stands for the one you have now.',
+  '      exporters: [otlp/current, otlphttp/uknows]',
+].join('\n')
+
+/** UKNOWS counts the spans it gets. It does not scale them up by a sample rate. */
+export const SAMPLING_NOTE = 'Keep sampling off. UKNOWS counts the requests that it gets. With OTEL_TRACES_SAMPLER=traceidratio and OTEL_TRACES_SAMPLER_ARG=0.1, UKNOWS shows 1 in 10 of your requests. Remove both settings, or set OTEL_TRACES_SAMPLER=parentbased_always_on.'
+
+export const STACKS = [
+  {
+    id: 'node',
+    label: 'Node.js',
+    summary: 'Add the OpenTelemetry Node.js packages. Load them when the app starts.',
+    manifests: ['package.json'],
+    frameworks: ['Express', 'Fastify', 'NestJS', 'Koa', 'Hapi'],
+    install: 'npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node',
+    files: [],
+    dockerfile: [
+      '# Final stage, after your app files and node_modules',
+      `ENV NODE_OPTIONS="--require ${NODE_REGISTER}"`,
+      SETTINGS_DOCKERFILE,
+      'CMD ["node", "server.js"]',
+    ].join('\n'),
+    start: `node --require ${NODE_REGISTER} server.js`,
+    // --require= has no space. With a space, a shell that loads otel.env runs the package path as a command.
+    platformEnv: [`NODE_OPTIONS=--require=${NODE_REGISTER}`],
+    option: {
+      title: 'Your app uses ES modules?',
+      summary: 'Use these lines when package.json has "type": "module", or when your app starts from an .mjs file. With the --require line alone, UKNOWS gets each request without its route.',
+      steps: [
+        'Add 1 more package: @opentelemetry/instrumentation.',
+        'Load OpenTelemetry with the 2 options below, in your Dockerfile, your start line or the NODE_OPTIONS setting on your platform.',
+        'Node prints an ExperimentalWarning about --experimental-loader when the app starts. You can ignore it.',
+      ],
+      snippets: [
+        { caption: 'Terminal: 1 more package', language: 'bash', code: 'npm install --save @opentelemetry/instrumentation' },
+        { caption: 'Dockerfile for ES modules', language: 'dockerfile', code: `ENV NODE_OPTIONS="${NODE_ESM_OPTIONS}"` },
+        { caption: 'Start line for ES modules', language: 'bash', code: `node ${NODE_ESM_OPTIONS} server.mjs` },
+        { caption: 'NODE_OPTIONS on your platform', language: 'text', code: NODE_ESM_OPTIONS },
+      ],
+    },
+    notes: [
+      'Replace server.js with the file that starts your server.',
+      'Install the packages as normal dependencies. Your production image must include them.',
+      'If your image already sets NODE_OPTIONS, add the --require option to that value.',
+      'If your app uses ES modules, use the steps in "Your app uses ES modules?". The --require line alone loses the route of each request.',
+      'If your repo uses yarn or pnpm, add the same packages with that tool.',
+      'OpenTelemetry listens for SIGTERM to send the last data. Because of that, Node no longer stops on SIGTERM by itself. Add this line to the file that starts your server: process.on("SIGTERM", () => { server.close(); setTimeout(() => process.exit(0), 5000).unref() }). Here server is what app.listen() returns. The line closes your server and stops the app in 5 seconds at most, also when a database or Redis client is still open. Without it, Docker, Kubernetes and systemd wait for their time limit and then kill the app.',
+      'Outside Google Cloud, the app log can show a MetadataLookupWarning when the app starts. OpenTelemetry looks for Google Cloud details and finds none. You can ignore it.',
+    ],
+  },
+  {
+    id: 'python',
+    label: 'Python',
+    summary: 'Add the OpenTelemetry packages for Python and for the libraries that your app uses. Start the app with opentelemetry-instrument.',
+    manifests: ['requirements.txt', 'pyproject.toml', 'Pipfile'],
+    frameworks: ['Django', 'Flask', 'FastAPI', 'Starlette', 'Falcon', 'Tornado'],
+    install: [
+      '[ -z "$(tail -c1 requirements.txt)" ] || echo >> requirements.txt',
+      'pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http',
+      "pip freeze | grep -E '^opentelemetry-(distro|exporter-otlp-proto-http)==' >> requirements.txt",
+      'opentelemetry-bootstrap -a requirements >> requirements.txt',
+      'pip install -r requirements.txt',
+    ].join('\n'),
+    files: [],
+    dockerfile: [
+      '# requirements.txt now lists the OpenTelemetry packages',
+      'RUN pip install --no-cache-dir -r requirements.txt',
+      SETTINGS_DOCKERFILE,
+      'CMD ["opentelemetry-instrument", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]',
+    ].join('\n'),
+    start: 'opentelemetry-instrument uvicorn main:app --host 0.0.0.0 --port 8000',
+    startRequired: 'Python still needs the start line. The settings alone do not start monitoring. Start the app with opentelemetry-instrument, also under systemd, Docker and SAE.',
+    notes: [
+      'Use Python 3.10 or later. The OpenTelemetry packages need it.',
+      'Run the install commands in the virtual environment of the app. Install the app packages first, because opentelemetry-bootstrap reads them.',
+      'Put opentelemetry-instrument in front of the command that starts your app now.',
+      'For Django, set DJANGO_SETTINGS_MODULE before the app starts.',
+      'opentelemetry-instrument works with 1 worker. For Gunicorn or uvicorn with more than 1 worker, follow the pre-fork server steps in the OpenTelemetry Python docs.',
+      'Remove the --reload option in production.',
+      'If your repo uses Poetry or uv, add the same packages with poetry add or uv add.',
+    ],
+  },
+  {
+    id: 'dotnet',
+    label: '.NET',
+    summary: 'Add the OpenTelemetry.AutoInstrumentation package. Start the app with instrument.sh.',
+    manifests: ['*.csproj', '*.sln'],
+    frameworks: ['ASP.NET Core', 'Minimal APIs', 'gRPC for ASP.NET Core'],
+    install: [
+      'dotnet add package OpenTelemetry.AutoInstrumentation',
+      'dotnet publish -c Release -r linux-x64 -o ./publish',
+    ].join('\n'),
+    files: [],
+    dockerfile: [
+      '# Build stage',
+      'RUN dotnet publish -c Release -r linux-x64 -o /app/publish',
+      '',
+      '# Final stage',
+      'WORKDIR /app',
+      'COPY --from=build /app/publish .',
+      dockerEnv([DOTNET_LOG_DIRECTORY]),
+      'ENTRYPOINT ["sh", "./instrument.sh", "dotnet", "OrdersApi.dll"]',
+    ].join('\n'),
+    start: 'sh ./publish/instrument.sh dotnet ./publish/OrdersApi.dll',
+    startRequired: '.NET still needs the start line. The settings alone do not start monitoring. Start the app with instrument.sh, also under systemd, Docker and SAE.',
+    extraSettings: {
+      lines: [DOTNET_LOG_DIRECTORY],
+      why: 'OpenTelemetry writes its log files to this folder. The app must be able to write to it.',
+    },
+    notes: [
+      'Replace OrdersApi.dll with the dll of your app.',
+      'Use .NET 8 or later.',
+      'The build needs a runtime identifier. Use linux-x64 or linux-arm64. Use linux-musl-x64 for Alpine images. On a Mac, use osx-arm64.',
+      'The package puts instrument.sh in the publish folder. The script starts your app with monitoring on.',
+      `Keep ${DOTNET_LOG_DIRECTORY} with the 5 settings. Without a folder that the app can write, the app stops when it starts. The default folder, /var/log/opentelemetry, is not writable on a Mac or in an image that runs as a user that is not root.`,
+      'If your app uses StackExchange.Redis, the build stops and names 1 more package and its version. Add that package. For OpenTelemetry.AutoInstrumentation 1.17.0, run dotnet add package OpenTelemetry.Instrumentation.StackExchangeRedis --version 1.19.0-beta.1.',
+      'To turn monitoring off for .NET, set OTEL_DOTNET_AUTO_TRACES_ENABLED=false.',
+    ],
+  },
+  {
+    id: 'java',
+    label: 'Java',
+    summary: `Add the OpenTelemetry Java agent ${JAVA_AGENT.version}. Start the JVM with -javaagent.`,
+    manifests: ['pom.xml', 'build.gradle', 'build.gradle.kts'],
+    frameworks: ['Spring Boot', 'Spring WebFlux', 'Quarkus', 'Micronaut', 'Jakarta EE', 'Dropwizard'],
+    install: [
+      `curl -fsSL -o ${JAVA_AGENT.file} ${JAVA_AGENT.url}`,
+      `echo "${JAVA_AGENT.sha256}  ${JAVA_AGENT.file}" | sha256sum -c -`,
+    ].join('\n'),
+    files: [],
+    dockerfile: [
+      '# Final stage',
+      `ADD --checksum=sha256:${JAVA_AGENT.sha256} --chmod=755 ${JAVA_AGENT.url} /otel/${JAVA_AGENT.file}`,
+      `ENV JAVA_TOOL_OPTIONS="-javaagent:/otel/${JAVA_AGENT.file}"`,
+      SETTINGS_DOCKERFILE,
+      'CMD ["java", "-jar", "app.jar"]',
+    ].join('\n'),
+    start: `java -javaagent:./${JAVA_AGENT.file} -jar app.jar`,
+    platformEnv: [`JAVA_TOOL_OPTIONS=-javaagent:/path/to/${JAVA_AGENT.file}`],
+    notes: [
+      `The agent is version ${JAVA_AGENT.version}. Check its SHA-256 checksum before you use it.`,
+      'In the JAVA_TOOL_OPTIONS line, replace /path/to with the folder of the agent.',
+      'On macOS, use shasum -a 256 -c - instead of sha256sum -c -.',
+      'Replace app.jar with your built app. Put -javaagent before -jar. Keep your other JVM options.',
+      'If your image already sets JAVA_TOOL_OPTIONS, add the -javaagent option to that value.',
+      'Keep --chmod=755 in the ADD line. It lets an app that runs as a non-root user open the /otel folder and load the agent.',
+      'ADD --checksum needs Docker 25 or later. On older Docker, put # syntax=docker/dockerfile:1 on the first line of the Dockerfile.',
+      'Use Java 8 or later. Use a JVM build. Native images need the OpenTelemetry starter for your framework.',
+      'To turn the agent off completely, set OTEL_JAVAAGENT_ENABLED=false.',
+    ],
+  },
+  {
+    id: 'go',
+    label: 'Go',
+    summary: 'Add the OpenTelemetry Go SDK and the middleware for your router. Add a short init file.',
+    manifests: ['go.mod'],
+    frameworks: ['net/http', 'Gin', 'Echo', 'chi'],
+    install: [
+      'go get go.opentelemetry.io/otel \\',
+      '  go.opentelemetry.io/otel/sdk \\',
+      '  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp \\',
+      '  go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp',
+      '# Gin only',
+      'go get go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin',
+      '# Echo v4 only',
+      'go get github.com/labstack/echo-otel/v4',
+    ].join('\n'),
+    files: [
+      { path: 'otel.go', language: 'go', summary: 'Add this file to your main package.', content: GO_INIT },
+      { path: 'main.go', language: 'go', summary: 'Change main like this. Keep only the middleware for your router.', content: GO_MAIN },
+    ],
+    dockerfile: [
+      '# Build stage: no change. otel.go builds into your binary.',
+      '# Final stage',
+      SETTINGS_DOCKERFILE,
+    ].join('\n'),
+    start: `go build -o ${EXAMPLE_SERVICE} . && ./${EXAMPLE_SERVICE}`,
+    notes: [
+      'Use Go 1.26 or later. The current OpenTelemetry Go modules need it. With an older Go, the build stops with a Go version error.',
+      'Call setupOTel at the start of main. The main.go code stops the server on Ctrl+C or SIGTERM. Then it calls the shutdown function, which sends the last data.',
+      'If your app already stops the server on SIGTERM, keep your code. Call the shutdown function after the server stops and before the app exits.',
+      'Use the middleware for your router. For net/http, wrap the ServeMux with withRoute, then with otelhttp.NewHandler. withRoute adds the route of each request. Gin and Echo add the route on their own.',
+      'For chi, add the route middleware before your routes. chi stops with an error when a middleware comes after a route.',
+      'For another router, call setRoute with the route of the request after the router picks it.',
+      'For outgoing HTTP calls, use otelhttp.NewTransport in your HTTP client. Pass the request context to each call.',
+      'For Echo v5, use github.com/labstack/echo-otel/v5.',
+      'Run go mod tidy. Then run your tests and build.',
+      'These steps add code at startup only. Your business logic stays the same.',
+    ],
+  },
+  {
+    id: 'php',
+    label: 'PHP',
+    summary: 'Add the OpenTelemetry extension and the Composer packages. Turn on autoload with OTEL_PHP_AUTOLOAD_ENABLED.',
+    manifests: ['composer.json'],
+    frameworks: ['Laravel', 'Symfony', 'Slim'],
+    install: [
+      'pecl install opentelemetry',
+      'composer config allow-plugins.php-http/discovery false',
+      'composer require --ignore-platform-req=ext-opentelemetry open-telemetry/sdk open-telemetry/exporter-otlp open-telemetry/opentelemetry-auto-laravel',
+    ].join('\n'),
+    files: [
+      { path: 'php.ini', language: 'ini', summary: 'Turn on the extension. Check it with php -m | grep opentelemetry.', content: '[opentelemetry]\nextension=opentelemetry.so' },
+    ],
+    dockerfile: [
+      '# Official php images',
+      'RUN pecl install opentelemetry \\',
+      ' && docker-php-ext-enable opentelemetry',
+      dockerEnv(['OTEL_PHP_AUTOLOAD_ENABLED=true']),
+    ].join('\n'),
+    start: 'OTEL_PHP_AUTOLOAD_ENABLED=true php artisan serve --no-reload',
+    platformEnv: ['OTEL_PHP_AUTOLOAD_ENABLED=true'],
+    notes: [
+      'Set OTEL_PHP_AUTOLOAD_ENABLED=true with the 5 settings. PHP needs it to start OpenTelemetry.',
+      'Keep --no-reload with php artisan serve. Without it, artisan serve does not pass the OTEL_ settings to your app.',
+      'For Symfony, use open-telemetry/opentelemetry-auto-symfony instead of the Laravel package.',
+      'For Slim, use open-telemetry/opentelemetry-auto-slim instead of the Laravel package.',
+      'The exporter needs a PSR-18 HTTP client. Laravel apps include Guzzle, which works. For other apps, run composer require guzzlehttp/guzzle.',
+      'The --ignore-platform-req option lets composer add the packages on a computer without the extension. The image installs the extension. If your Dockerfile runs composer install in a stage without the extension, such as the composer image, add --ignore-platform-req=ext-opentelemetry to that line too.',
+      'PHP-FPM removes environment variables by default. Set clear_env = no in the pool config, or pass each setting with env[NAME].',
+      'On Alpine images, install the build tools first with apk add --no-cache $PHPIZE_DEPS.',
+    ],
+  },
+  {
+    id: 'ruby',
+    label: 'Ruby',
+    summary: 'Add the OpenTelemetry gems. Add an initializer that turns on all instrumentation.',
+    manifests: ['Gemfile'],
+    frameworks: ['Rails', 'Sinatra', 'Rack'],
+    install: 'bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all',
+    files: [
+      { path: 'config/initializers/opentelemetry.rb', language: 'ruby', summary: 'Add this file for Rails.', content: RUBY_INITIALIZER },
+    ],
+    dockerfile: [
+      '# bundle install adds the gems from Gemfile.lock',
+      'RUN bundle install',
+      SETTINGS_DOCKERFILE,
+      'CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]',
+    ].join('\n'),
+    start: 'bundle exec rails server',
+    notes: [
+      'For Sinatra, put the same code in config.ru after require "sinatra" and before your app loads.',
+      'For a plain Rack app, put the same code in config.ru. Below it, add use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args).',
+      'Commit Gemfile and Gemfile.lock.',
+    ],
+  },
+  {
+    id: 'otel',
+    label: 'I already use OpenTelemetry',
+    summary: 'Keep your OpenTelemetry setup. Point it at UKNOWS with the same settings.',
+    manifests: ['package.json', 'requirements.txt', 'pyproject.toml', '*.csproj', 'pom.xml', 'build.gradle', 'go.mod', 'composer.json', 'Gemfile'],
+    frameworks: ['Any app that already lists OpenTelemetry packages: @opentelemetry/*, opentelemetry-*, OpenTelemetry.*, io.opentelemetry, go.opentelemetry.io or open-telemetry/*'],
+    install: '# No new packages. Keep the OpenTelemetry packages that you use now.',
+    files: [],
+    dockerfile: ['# Final stage. Your SDK reads these settings at startup.', SETTINGS_DOCKERFILE].join('\n'),
+    start: '# Keep your start command. Your SDK reads the OTEL_ settings when the app starts.',
+    warning: 'These settings send your traces to UKNOWS instead of the backend that gets them now. OTEL_METRICS_EXPORTER=none and OTEL_LOGS_EXPORTER=none also stop your metrics and logs. To keep your current backend, add UKNOWS to an OpenTelemetry Collector instead. See "Keep your current backend".',
+    option: {
+      title: 'Keep your current backend: add UKNOWS to your Collector',
+      summary: 'Your apps keep their settings and send to your OpenTelemetry Collector. The Collector sends traces to your current backend and to UKNOWS.',
+      steps: [
+        'Add the otlphttp/uknows exporter below to your Collector config.',
+        'Add otlphttp/uknows to the exporters of your traces pipeline. Keep the exporters that you have.',
+        'Set UKNOWS_KEY as a secret on the Collector, as in step 3. Use the key only, without x-uknows-key=.',
+        'Restart the Collector.',
+        'Newer Collectors name this exporter otlp_http. If your Collector says that otlphttp is deprecated, rename otlphttp/uknows to otlp_http/uknows in both places.',
+      ],
+      snippets: [{ caption: 'Collector config', language: 'yaml', code: COLLECTOR_CONFIG }],
+    },
+    notes: [
+      'Remove exporter addresses and headers from your code. Then the OTEL_ settings apply.',
+      'Set OTEL_TRACES_EXPORTER to otlp, or remove it.',
+      'UKNOWS takes OTLP over HTTP. If your code creates a gRPC exporter, change it to the HTTP exporter.',
+      'For Python, use the opentelemetry-exporter-otlp-proto-http package. For Go, use the otlptracehttp exporter.',
+      'If you send data through an OpenTelemetry Collector, add UKNOWS to the Collector. The config is in "Keep your current backend".',
+      SAMPLING_NOTE,
+    ],
+  },
+]
+
+/**
+ * The settings of 1 stack as env lines, for otel.env and the settings tab:
+ * the 5 settings, then for each extra group a # line and its lines. A shell,
+ * systemd and docker run --env-file skip the # lines.
+ */
+export function stackSettingsEnv(stack) {
+  const lines = [SETTINGS_ENV]
+  if (stack.extraSettings) lines.push(`# For ${stack.label}: ${stack.extraSettings.why}`, ...stack.extraSettings.lines)
+  if (stack.platformEnv?.length) lines.push(`# For ${stack.label}: this loads OpenTelemetry when the app starts.`, ...stack.platformEnv)
+  return lines.join('\n')
+}
+
+/** A stricter way to store the key, shown folded under the host. */
+
+/** The prompt line, exactly. bash only: zsh reads -p as a coprocess. */
+export const KEY_PROMPT = "read -rsp 'Paste your UKNOWS key: ' UKNOWS_KEY; echo"
+/** Stops the script, not the terminal, when no key was pasted. */
+export const KEY_EMPTY_GUARD = '[ -n "$UKNOWS_KEY" ] || { echo "No key entered. Nothing changed."; exit 1; }'
+/** The path of the key file on a VM or Docker host. Only root can read it. */
+export const KEY_FILE = '/etc/uknows.env'
+
+/**
+ * A bash script that asks for the key without showing it. The ( ) block is a
+ * subshell: exit stops the block, not the terminal, and the key is gone when
+ * the block ends. bash reads the whole block before it runs, so pasted lines
+ * never become the key.
+ */
+export function keyScript(setup, body, where = 'Run in bash') {
+  return [
+    `# ${where}. The key does not show on the screen. It is gone when the ( ) block ends.`,
+    '(',
+    ...[...setup, KEY_PROMPT, KEY_EMPTY_GUARD, ...body].map((line) => `  ${line}`),
+    ')',
+  ].join('\n')
+}
+
+export const BASH_STEP = 'Open a bash terminal. On macOS, type bash first. On Windows, use Azure Cloud Shell or WSL.'
+
+/**
+ * The lines before the key prompt of a script that changes apps one by one.
+ * With DRY_RUN=1 the script only checks that each app exists and says what it
+ * would change. It never asks for the key.
+ */
+export function dryRun(apps, show, change) {
+  return [
+    'RESOURCE_GROUP=orders-prod',
+    `APPS="${apps}"   # only these apps get the key`,
+    'DRY_RUN=1   # 1: list the changes only. 0: make them.',
+    'if [ "$DRY_RUN" = 1 ]; then',
+    '  for APP in $APPS; do',
+    `    ${show} -g "$RESOURCE_GROUP" -n "$APP" -o none &&`,
+    `    echo "Would set the key on $APP. ${change}"`,
+    '  done',
+    '  exit 0',
+    'fi',
+  ]
+}
+
+export const QUIET_TIME = 'Run it at a quiet time.'
+
+export const HOSTS = [
+  {
+    id: 'azure-container-apps',
+    label: 'Azure Container Apps',
+    summary: 'Set the key as a secret on the container apps that you name.',
+    steps: [
+      BASH_STEP,
+      'Sign in with az login.',
+      'Set RESOURCE_GROUP to the resource group of your apps. Set APPS to the apps that send data to UKNOWS. To list the apps, run az containerapp list -g orders-prod --query "[].name" -o tsv.',
+      'Run the script with DRY_RUN=1 first. It checks each app and says what it would change. It changes nothing.',
+      'Set DRY_RUN=0 and run it again. Paste your key when it asks. The key does not show on the screen.',
+      `Each app starts a new revision with the key. ${QUIET_TIME}`,
+    ],
+    snippets: [
+      {
+        caption: 'Set the key on your container apps',
+        language: 'bash',
+        code: keyScript(dryRun('orders-api payments', 'az containerapp show', 'It would start a new revision.'), [
+          'for APP in $APPS; do',
+          '  az containerapp secret set -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+          '    --secrets "uknows-otlp-headers=x-uknows-key=$UKNOWS_KEY" &&',
+          '  az containerapp update -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+          '    --set-env-vars "OTEL_EXPORTER_OTLP_HEADERS=secretref:uknows-otlp-headers" &&',
+          '  echo "Set the key on $APP."',
+          'done',
+        ]),
+      },
+    ],
+    notes: [
+      'Run the script on your own computer or in Azure Cloud Shell. Do not run it on a shared server. Other users of a shared server can see the commands that run, and the az command gets the key.',
+      'When you add a new app, run the script again with APPS set to the new app.',
+      'If an app has more than 1 container, add --container-name to the update command.',
+    ],
+    stricter: {
+      title: 'Stricter option: keep the key in Azure Key Vault',
+      summary: 'The key stays in Key Vault. Each app reads it with its managed identity. The key never passes through a terminal.',
+      steps: [
+        'In the Azure portal, open your key vault. Create a secret named uknows-otlp-headers. Set its value to x-uknows-key=<key>.',
+        'Turn on the system-assigned managed identity of each container app.',
+        'Give each identity the Key Vault Secrets User role on the key vault.',
+        'Set APPS and SECRET_URI. Run the script with DRY_RUN=1 first. Then set DRY_RUN=0 and run it again at a quiet time.',
+      ],
+      snippets: [
+        {
+          caption: 'Use the Key Vault secret on your container apps',
+          language: 'bash',
+          code: [
+            '# Run in bash. This script never sees the key.',
+            '(',
+            ...dryRun('orders-api payments', 'az containerapp show', 'It would start a new revision.').map((line) => `  ${line}`),
+            '  SECRET_URI=https://my-vault.vault.azure.net/secrets/uknows-otlp-headers',
+            '  for APP in $APPS; do',
+            '    az containerapp secret set -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+            '      --secrets "uknows-otlp-headers=keyvaultref:$SECRET_URI,identityref:system" &&',
+            '    az containerapp update -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+            '      --set-env-vars "OTEL_EXPORTER_OTLP_HEADERS=secretref:uknows-otlp-headers" &&',
+            '    echo "Set the key on $APP."',
+            '  done',
+            ')',
+          ].join('\n'),
+        },
+      ],
+    },
+  },
+  {
+    id: 'azure-app-service',
+    label: 'Azure App Service',
+    summary: 'Set the key as an app setting on the web apps that you name.',
+    steps: [
+      BASH_STEP,
+      'Sign in with az login.',
+      'Set RESOURCE_GROUP and APPS to your web apps. Run the script with DRY_RUN=1 first. It checks each app and says what it would change.',
+      'Set DRY_RUN=0 and run it again. Paste your key when it asks. The key does not show on the screen.',
+      `App Service restarts each app with the key. ${QUIET_TIME}`,
+    ],
+    snippets: [
+      {
+        caption: 'Set the key on your web apps',
+        language: 'bash',
+        code: keyScript(dryRun('orders-api payments', 'az webapp show', 'It would restart the app.'), [
+          'for APP in $APPS; do',
+          '  az webapp config appsettings set -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+          '    --settings "OTEL_EXPORTER_OTLP_HEADERS=x-uknows-key=$UKNOWS_KEY" &&',
+          '  echo "Set the key on $APP."',
+          'done',
+        ]),
+      },
+    ],
+    notes: [
+      'Run the script on your own computer or in Azure Cloud Shell. Do not run it on a shared server. Other users of a shared server can see the commands that run, and the az command gets the key.',
+      'If your app does not start from your Dockerfile, add the 5 settings as app settings too.',
+      'For Python and .NET, put the start line of your stack in the startup command of the app.',
+      'For a deployment slot, add --slot with the name of the slot to both az commands.',
+    ],
+    stricter: {
+      title: 'Stricter option: keep the key in Azure Key Vault',
+      summary: 'The key stays in Key Vault. Each app reads it with its managed identity. The key never passes through a terminal.',
+      steps: [
+        'In the Azure portal, open your key vault. Create a secret named uknows-otlp-headers. Set its value to x-uknows-key=<key>.',
+        'Turn on the system-assigned managed identity of each web app.',
+        'Give each identity the Key Vault Secrets User role on the key vault.',
+        'Set APPS and SECRET_URI. Run the script with DRY_RUN=1 first. Then set DRY_RUN=0 and run it again at a quiet time.',
+      ],
+      snippets: [
+        {
+          caption: 'Use the Key Vault secret on your web apps',
+          language: 'bash',
+          code: [
+            '# Run in bash. This script never sees the key.',
+            '(',
+            ...dryRun('orders-api payments', 'az webapp show', 'It would restart the app.').map((line) => `  ${line}`),
+            '  SECRET_URI=https://my-vault.vault.azure.net/secrets/uknows-otlp-headers',
+            '  for APP in $APPS; do',
+            '    az webapp config appsettings set -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+            '      --settings "OTEL_EXPORTER_OTLP_HEADERS=@Microsoft.KeyVault(SecretUri=$SECRET_URI)" &&',
+            '    echo "Set the key on $APP."',
+            '  done',
+            ')',
+          ].join('\n'),
+        },
+      ],
+    },
+  },
+  {
+    id: 'aws-ecs',
+    label: 'AWS ECS and Fargate',
+    summary: 'Store the key in AWS Secrets Manager. Each task definition reads it as a secret.',
+    steps: [
+      'Open a bash terminal. On macOS, type bash first. On Windows, use AWS CloudShell or WSL.',
+      'Sign in to the AWS CLI, for example with aws sso login.',
+      'Run the script once for each environment. Paste your key when it asks. The script prints the ARN of the secret.',
+      'In the task definition of each app, add the secret to the container. Use the ARN that the script printed.',
+      'Let the task execution role of each app read the secret: it needs secretsmanager:GetSecretValue on it.',
+      `Register the new task definition. Then update the service to use it. ECS replaces the running tasks. ${QUIET_TIME}`,
+    ],
+    snippets: [
+      {
+        caption: 'Store the key in Secrets Manager',
+        language: 'bash',
+        code: keyScript(['SECRET_NAME=uknows-otlp-headers-prod'], [
+          "printf 'x-uknows-key=%s' \"$UKNOWS_KEY\" \\",
+          '  | aws secretsmanager create-secret --name "$SECRET_NAME" \\',
+          '      --secret-string file:///dev/stdin --query ARN --output text',
+        ]),
+      },
+      {
+        caption: 'Add the secret to the container in your task definition',
+        language: 'json',
+        code: [
+          '"secrets": [',
+          '  {',
+          '    "name": "OTEL_EXPORTER_OTLP_HEADERS",',
+          '    "valueFrom": "arn:aws:secretsmanager:<region>:<account>:secret:uknows-otlp-headers-prod-AbCdEf"',
+          '  }',
+          ']',
+        ].join('\n'),
+      },
+    ],
+    notes: [
+      'The key goes to the AWS CLI through a pipe, not as an argument. Other users of the computer cannot see it.',
+      'If your image does not have ENV lines for the 5 settings, add the 5 settings to the environment of the container in the task definition.',
+      'ECS reads the secret when a task starts. To change the key, store the new key with aws secretsmanager put-secret-value. Then update the service with --force-new-deployment.',
+      'You can use AWS Systems Manager Parameter Store instead. Store a SecureString parameter and put its ARN in valueFrom.',
+      'For EKS, use the Kubernetes steps. For EC2, use the VM steps.',
+    ],
+  },
+  {
+    id: 'kubernetes',
+    label: 'Kubernetes (any cluster)',
+    summary: 'Store the key in a Kubernetes secret. Load it into each deployment with envFrom.',
+    steps: [
+      BASH_STEP,
+      'Create the secret once in each namespace that runs your apps. Paste your key when the script asks.',
+      'Add envFrom to each deployment. Commit this change with the 5 settings.',
+      'If your image does not have ENV lines for the 5 settings, add them to env in the deployment too.',
+      'Apply the deployment. Kubernetes starts new pods with the key.',
+    ],
+    snippets: [
+      {
+        caption: 'Create the secret',
+        language: 'bash',
+        code: keyScript(['NAMESPACE=orders'], [
+          "printf 'x-uknows-key=%s' \"$UKNOWS_KEY\" \\",
+          '  | kubectl create secret generic uknows -n "$NAMESPACE" \\',
+          '      --from-file=OTEL_EXPORTER_OTLP_HEADERS=/dev/stdin --dry-run=client -o yaml \\',
+          '  | kubectl apply -f -',
+        ]),
+      },
+      {
+        caption: 'Load the secret in your deployment',
+        language: 'yaml',
+        code: [
+          '# Adds OTEL_EXPORTER_OTLP_HEADERS from the uknows secret.',
+          'spec:',
+          '  template:',
+          '    spec:',
+          '      containers:',
+          `        - name: ${EXAMPLE_SERVICE}`,
+          '          envFrom:',
+          '            - secretRef:',
+          '                name: uknows',
+        ].join('\n'),
+      },
+      {
+        caption: 'The 5 settings in your deployment, if your image does not have them',
+        language: 'yaml',
+        code: [
+          'spec:',
+          '  template:',
+          '    spec:',
+          '      containers:',
+          `        - name: ${EXAMPLE_SERVICE}`,
+          '          env:',
+          ...SETTINGS.flatMap((setting) => [`            - name: ${setting.name}`, `              value: ${setting.value}`]),
+        ].join('\n'),
+      },
+      {
+        caption: 'Helm: the same in values.yaml, if your chart passes env and envFrom to the container',
+        language: 'yaml',
+        code: [
+          '# Charts differ. Use the keys that your chart reads.',
+          'env:',
+          ...SETTINGS.flatMap((setting) => [`  - name: ${setting.name}`, `    value: ${setting.value}`]),
+          'envFrom:',
+          '  - secretRef:',
+          '      name: uknows',
+        ].join('\n'),
+      },
+    ],
+    notes: [
+      'The same steps work on any cluster: Amazon EKS, Azure AKS, Google GKE, Alibaba ACK and your own clusters.',
+      'The key goes to kubectl through a pipe, not as an argument. Other users of the computer cannot see it.',
+      'To change the key, run the script again. Then run kubectl rollout restart for each deployment.',
+    ],
+  },
+  {
+    id: 'alibaba-sae',
+    label: 'Alibaba Cloud SAE',
+    summary: 'Store the key in an SAE secret. Reference it in the environment variables of each app.',
+    steps: [
+      'Open the SAE console. Select the region and namespace of your apps.',
+      'Create a secret named uknows with the key and value below.',
+      'Open each app. Edit its environment variables.',
+      'Add a variable named OTEL_EXPORTER_OTLP_HEADERS. Make it reference the secret uknows and the key OTEL_EXPORTER_OTLP_HEADERS.',
+      'If your image does not have ENV lines for the 5 settings, add the 5 settings as environment variables too.',
+      'Deploy the app. SAE restarts it with the key.',
+    ],
+    snippets: [
+      {
+        caption: 'Secret content',
+        language: 'text',
+        code: ['Secret name: uknows', 'Key: OTEL_EXPORTER_OTLP_HEADERS', `Value: ${SECRET.value}`].join('\n'),
+      },
+    ],
+    notes: [
+      'Replace <key> with your key in the SAE console. Do not put the key in a file or a chat.',
+      'SAE restarts the app when you deploy. Deploy at a quiet time.',
+    ],
+  },
+  {
+    id: 'vm-docker',
+    label: 'Any VM or Docker',
+    summary: `Store the key in ${KEY_FILE} on each host. Load the file when the app starts.`,
+    steps: [
+      'On each host, run the script in bash. Paste your key when it asks.',
+      `The script creates ${KEY_FILE}. Only root can read it.`,
+      `For Docker, add --env-file ${KEY_FILE} to docker run.`,
+      `For systemd, add EnvironmentFile=${KEY_FILE} to the service.`,
+      'Restart the app.',
+    ],
+    snippets: [
+      {
+        caption: 'Create the key file',
+        language: 'bash',
+        code: keyScript([], [
+          `sudo touch ${KEY_FILE}`,
+          `sudo chmod 600 ${KEY_FILE}`,
+          `printf 'OTEL_EXPORTER_OTLP_HEADERS=x-uknows-key=%s\\n' "$UKNOWS_KEY" | sudo tee ${KEY_FILE} > /dev/null &&`,
+          `echo "Saved the key in ${KEY_FILE}."`,
+        ], 'Run in bash on each host'),
+      },
+      {
+        caption: 'Docker',
+        language: 'bash',
+        code: ['# Loads OTEL_EXPORTER_OTLP_HEADERS from the key file.', `sudo docker run -d --env-file ${KEY_FILE} ${EXAMPLE_SERVICE}:latest`].join('\n'),
+      },
+      {
+        caption: 'systemd service',
+        language: 'ini',
+        code: [
+          '[Service]',
+          `# The 5 settings, from ${SETTINGS_FILE.path} in your repo.`,
+          `EnvironmentFile=/opt/${EXAMPLE_SERVICE}/${SETTINGS_FILE.path}`,
+          '# Loads OTEL_EXPORTER_OTLP_HEADERS from the key file.',
+          `EnvironmentFile=${KEY_FILE}`,
+        ].join('\n'),
+      },
+    ],
+    notes: [
+      'Docker reads the file as the user that runs docker. Run docker with sudo or as root.',
+      'If your image does not have ENV lines for the 5 settings, add --env-file otel.env to docker run too.',
+      `For Docker Compose, add env_file: ${KEY_FILE} to the service.`,
+      'After you change a systemd service, run sudo systemctl daemon-reload. Then restart the service.',
+      `If you start the app from a shell as a user that is not root, make that user the owner of the key file: sudo chown <user> ${KEY_FILE}.`,
+      'The same steps work on any Linux VM or server: Amazon EC2, Azure VMs, Google Compute Engine, Alibaba ECS and servers in your own data center.',
+    ],
+  },
+  {
+    id: 'github-actions',
+    label: 'GitHub Actions',
+    summary: 'Store the key as a GitHub environment secret, once for each environment. Your deploy workflow sets it on your app.',
+    steps: [
+      'Install the GitHub CLI. Sign in with gh auth login.',
+      'Run the command once for each environment. Paste x-uknows-key=<key> for that environment when it asks for the value. The value does not show on the screen.',
+      'In your deploy workflow, add environment: production to the deploy job. Then add the step below before your deploy step. It reads the secret and sets it on your app. The example is for Azure Container Apps.',
+    ],
+    snippets: [
+      {
+        caption: 'Set the environment secret',
+        language: 'bash',
+        code: 'gh secret set OTEL_EXPORTER_OTLP_HEADERS --env production --repo my-org/orders-api',
+      },
+      {
+        caption: 'Set the key in your deploy workflow',
+        language: 'yaml',
+        code: [
+          '# Add this step before your deploy step. The job has environment: production.',
+          '# An earlier step signs in to Azure.',
+          '- name: Set the UKNOWS key',
+          '  env:',
+          '    RESOURCE_GROUP: orders-prod',
+          '    OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}',
+          `  run: az containerapp secret set -g "$RESOURCE_GROUP" -n ${EXAMPLE_SERVICE} --secrets "uknows-otlp-headers=$OTEL_EXPORTER_OTLP_HEADERS"`,
+        ].join('\n'),
+      },
+      {
+        caption: 'Or: 1 organization secret for many repos',
+        language: 'bash',
+        code: 'gh secret set OTEL_EXPORTER_OTLP_HEADERS --org my-org --visibility private',
+      },
+    ],
+    notes: [
+      'Replace my-org/orders-api with your repo. Replace production with the name of your GitHub environment.',
+      'Each environment has its own key. gh secret set OTEL_EXPORTER_OTLP_HEADERS --env production sets the key for production only. For staging, run it again with --env staging and the staging key.',
+      'An organization secret holds 1 key. Use it only when all the repos that read it deploy to the same environment.',
+      '--visibility private shares the organization secret with the private repos of the organization. Public repos cannot use it.',
+      'To share it with some repos only, use --visibility selected --repos orders-api,payments instead.',
+      'In the example, replace orders-prod and orders-api with your resource group and app.',
+      'The app must load the secret. Make your deploy command set OTEL_EXPORTER_OTLP_HEADERS=secretref:uknows-otlp-headers, as the Azure Container Apps script does.',
+      'On other platforms, pass the secret the same way to the step that sets your app settings.',
+    ],
+  },
+]
+
+/** Said plainly, on the page and in llms.txt. */
+export const SERVERLESS = 'Serverless functions are not supported yet: AWS Lambda, Azure Functions, Google Cloud Functions and Alibaba Function Compute. Apps in containers, on Kubernetes and on VMs work.'
+
+const KEY_ANSWERS                       = [
+  { answer: '"workspace" and "environment"', meaning: 'The key works. It sends data to that workspace and environment.' },
+  { answer: '"keyState": "retiring"', meaning: 'The key still works until the time in "retiresAt". A new key replaced it. Set the new key.' },
+  { answer: 'ingest_key_invalid', meaning: 'UKNOWS does not know this key. Copy the whole key again, with no spaces or quotes.' },
+  { answer: 'ingest_key_revoked', meaning: 'The key no longer works. An Admin revoked it, a new key replaced it, or its environment was turned off. Get a new key from an Admin of your workspace.' },
+  { answer: 'workspace_paused', meaning: 'Your workspace is paused. Talk to us to start it again.' },
+  { answer: 'rate_limited', meaning: 'Too many checks from your address. Wait 1 minute.' },
+]
+
+/**
+ * Check a key before you deploy: the ping route of the site says which
+ * workspace and environment the key sends to, or why it is refused. A second
+ * line checks that a host reaches the ingest address.
+ */
+export const KEY_CHECK = {
+  id: 'check-key',
+  title: 'Check your key',
+  summary: 'Check the key before you deploy. Then you know that the key works, and for which workspace and environment.',
+  steps: [
+    'Run the script in bash on your own computer. Paste your key when it asks. The key does not show on the screen.',
+    'Read the answer. The list below says what each answer means.',
+    'Run the network check on a host that runs your app.',
+  ],
+  snippet: {
+    caption: 'Check the key',
+    language: 'bash',
+    code: keyScript([], [
+      `printf '${SECRET.header}: %s\\n' "$UKNOWS_KEY" | curl -sS -H @- ${PING_URL}`,
+      'echo',
+    ]),
+  },
+  answers: KEY_ANSWERS,
+  network: {
+    caption: 'Check that your app can reach UKNOWS',
+    language: 'bash',
+    code: `curl -sS -o /dev/null -w '%{http_code}\\n' https://${INGEST_HOST}/otlp/v1/traces`,
+  },
+  networkText: 'Any 3-digit number means the host reaches UKNOWS. 000 or an error means it cannot. Then check DNS, the firewall and any proxy.',
+}
+
+/**
+ * How to load otel.env when the app does not start from a Dockerfile with the
+ * ENV lines. The Dockerfile ENV lines stay the main path.
+ */
+export const SETTINGS_FILE_LOADERS = [
+  {
+    id: 'shell',
+    label: 'Plain start',
+    summary: `Load the file and the key file in the shell that starts your app. Then run the start line for your stack. The key file belongs to root. Run the start as root. Or make the app user the owner with sudo chown <user> ${KEY_FILE}, then run the start as that user. Do not use chmod to let more users read the key file.`,
+    snippet: {
+      caption: 'Load the settings and the key, then start the app',
+      language: 'bash',
+      code: [
+        '# Run in bash, in the folder of the service.',
+        `# Run as root, or as the owner of ${KEY_FILE}. Only they can read it.`,
+        'set -a',
+        `. ./${SETTINGS_FILE.path}        # the 5 settings`,
+        `. ${KEY_FILE}   # the key file from step 3`,
+        'set +a',
+        '# Now run the start line for your stack.',
+      ].join('\n'),
+    },
+  },
+  {
+    id: 'systemd',
+    label: 'systemd',
+    summary: 'Add the file and the key file to the service. Then restart the service.',
+    snippet: {
+      caption: 'systemd service',
+      language: 'ini',
+      code: [
+        '[Service]',
+        `# The 5 settings, from ${SETTINGS_FILE.path} in your repo.`,
+        `EnvironmentFile=/opt/${EXAMPLE_SERVICE}/${SETTINGS_FILE.path}`,
+        '# The key file from step 3.',
+        `EnvironmentFile=${KEY_FILE}`,
+      ].join('\n'),
+    },
+  },
+  {
+    id: 'docker',
+    label: 'Docker',
+    summary: 'If your Dockerfile does not have the ENV lines, pass the file and the key file to docker run.',
+    snippet: {
+      caption: 'docker run',
+      language: 'bash',
+      code: [
+        '# Loads the 5 settings and the key.',
+        `sudo docker run -d --env-file ${SETTINGS_FILE.path} --env-file ${KEY_FILE} ${EXAMPLE_SERVICE}:latest`,
+      ].join('\n'),
+    },
+  },
+  {
+    id: 'alibaba-sae',
+    label: 'Alibaba Cloud SAE',
+    summary: 'Open each app in the SAE console. Add the 5 settings as environment variables. If your stack has a line that loads OpenTelemetry, add it too. Then set the key as in step 3.',
+    snippet: {
+      caption: 'Environment variables',
+      language: 'text',
+      code: SETTINGS_ENV,
+    },
+    listsSettings: true,
+  },
+]
+
+export const TROUBLESHOOTING = [
+  {
+    id: 'no-data',
+    problem: 'No data after 10 minutes',
+    steps: [
+      'Send a few requests to your app. UKNOWS shows the requests that your app gets.',
+      'Restart or redeploy the app after you set the key.',
+      'Compare the names and values of the 5 settings with this page.',
+      'Run "Check your key" in step 3.',
+      'Open Ingest keys on your workspace home. It shows the uploads UKNOWS rejected for each key, and why.',
+      `Make sure that the app can reach ${INGEST_HOST} on port 443.`,
+      'Remove OTEL_SDK_DISABLED, or set it to false.',
+      'Read the app log for OpenTelemetry export errors. Some SDKs log nothing when UKNOWS refuses the key.',
+    ],
+  },
+  {
+    id: 'unauthorized',
+    problem: 'The key is not accepted (401)',
+    cause: 'UKNOWS does not accept the key. The key is wrong or in the wrong format, or it was revoked. Your app may not show this. Some OpenTelemetry SDKs, Node.js among them, drop the 401 and log nothing.',
+    steps: [
+      'Run "Check your key" in step 3. It says if the key is invalid or revoked.',
+      'Open Ingest keys on your workspace home. It shows the uploads UKNOWS rejected for each key, and why.',
+      'Copy the key again. Set the secret again.',
+      'Use the format x-uknows-key=<key>. Remove spaces and quotes.',
+      'Restart the app.',
+    ],
+  },
+  {
+    id: 'forbidden',
+    problem: 'The app log shows 403 (access stopped)',
+    cause: 'Your workspace is paused or your key is revoked.',
+    steps: [
+      'Talk to us to start the workspace again or to get a new key.',
+    ],
+  },
+  {
+    id: 'too-many',
+    problem: 'The app log shows 429 (too many requests)',
+    cause: 'Each key can send 200 requests a second, with short bursts up to 400. Your apps sent more.',
+    steps: [
+      'Keep the batch settings of OpenTelemetry. They send many traces in 1 request.',
+      'Talk to us if your apps need more.',
+    ],
+  },
+  {
+    id: 'missing-jobs',
+    problem: 'Queue consumers or batch jobs do not show',
+    cause: 'UKNOWS drops traces that have links. Queue consumers and batch jobs often add links.',
+    steps: [
+      'Check the requests of the same app. They still show.',
+      'Talk to us if you need these traces. We are working on it.',
+    ],
+  },
+  {
+    id: 'low-counts',
+    problem: 'UKNOWS shows fewer requests than your app gets',
+    cause: 'Your app samples traces. UKNOWS counts only the requests that it gets.',
+    steps: [
+      'Remove OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG, or set OTEL_TRACES_SAMPLER=parentbased_always_on.',
+      'Remove any sampler from the OpenTelemetry code of the app.',
+      'Restart the app.',
+    ],
+  },
+  {
+    id: 'other-apm',
+    problem: 'Your app already uses another APM agent',
+    cause: '2 tracing agents in 1 app can conflict.',
+    steps: [
+      'Use 1 tracing agent in each app.',
+      'Remove the other agent, or turn off its tracing, before you add UKNOWS.',
+      'If your app already uses OpenTelemetry, use the steps for "I already use OpenTelemetry".',
+    ],
+  },
+  {
+    id: 'turn-off',
+    problem: 'Turn monitoring off',
+    steps: [
+      'Set OTEL_SDK_DISABLED=true on the platform.',
+      'Restart the app.',
+      'For .NET, set OTEL_DOTNET_AUTO_TRACES_ENABLED=false.',
+      'To turn monitoring on again, remove the setting and restart the app.',
+    ],
+  },
+]
+
+/**
+ * OWNER DECISION 7 (PROGRAM.md, finding D-27): how many days UKNOWS keeps
+ * workspace data. The page said 30 days, but no store setting keeps data that
+ * long: SigNoz keeps traces for 7 or 15 days by default. Until the owner picks
+ * a number and the store is set and checked, this stays null and the page
+ * gives no number. Set it to the decided number of days, for example 30.
+ */
+export const RETENTION_DAYS = null