From a66c9880fc23cf7578d9cf795a7c3b2b5e13764a Mon Sep 17 00:00:00 2001 From: Dotan Simha Date: Sun, 26 Oct 2025 16:22:35 +0200 Subject: [PATCH] docs(router): added documentation for env vars --- .../src/content/router/configuration/_meta.ts | 1 + .../configuration/environment-variables.mdx | 34 +++++++++++++++++++ .../content/router/configuration/graphiql.mdx | 17 ++++++++++ .../src/content/router/configuration/http.mdx | 2 ++ .../content/router/configuration/index.mdx | 3 ++ .../src/content/router/configuration/log.mdx | 3 ++ .../router/configuration/supergraph.mdx | 4 +++ 7 files changed, 64 insertions(+) create mode 100644 packages/web/docs/src/content/router/configuration/environment-variables.mdx create mode 100644 packages/web/docs/src/content/router/configuration/graphiql.mdx diff --git a/packages/web/docs/src/content/router/configuration/_meta.ts b/packages/web/docs/src/content/router/configuration/_meta.ts index 4043b224a4..905cb965ca 100644 --- a/packages/web/docs/src/content/router/configuration/_meta.ts +++ b/packages/web/docs/src/content/router/configuration/_meta.ts @@ -1,3 +1,4 @@ export default { index: 'Overview', + 'environment-variables': 'Environment Variables', }; diff --git a/packages/web/docs/src/content/router/configuration/environment-variables.mdx b/packages/web/docs/src/content/router/configuration/environment-variables.mdx new file mode 100644 index 0000000000..10539b3e5a --- /dev/null +++ b/packages/web/docs/src/content/router/configuration/environment-variables.mdx @@ -0,0 +1,34 @@ +--- +title: 'Environment Variables' +--- + +# Environment Variables + +## Available Environment Variables + +The following environment variables are accepted by the router, and they override other +configurations that can be set in the router's configuration file (`router.config.yaml`): + +| Name | Accepted Values | Overrides (YAML) | +| ------------------------ | ---------------------------------------------------- | -------------------------------------------------------------- | +| `LOG_LEVEL` | `trace` / `debug` / `info` / `warn` / `error` | [`log.level`](./log#level) | +| `LOG_FORMAT` | `json` / `pretty-tree` / `pretty-compact` | [`log.format`](./log#format) | +| `LOG_FILTER` | `string` | [`log.filter`](./log#filter) | +| `GRAPHIQL_ENABLED` | `true` / `false` | [`graphiql.enabled`](./graphiql#enabled) | +| `PORT` | `number` (port number) | [`http.port`](./http#port) | +| `HOST` | `string` (host name or IP address) | [`http.host`](./http#host) | +| `SUPERGRAPH_FILE_PATH` | `string` (relative or absolute path to a local file) | [`supergraph[file].path`](./supergraph#path) | +| `HIVE_CDN_ENDPOINT` | `string` (full url to Hive CDN supergraph artifact) | [`supergraph[hive].endpoint`](./supergraph#endpoint) | +| `HIVE_CDN_KEY` | `string` (Hive CDN key) | [`supergraph[hive].key`](./supergraph#key) | +| `HIVE_CDN_POLL_INTERVAL` | `string` (human-readable, for example: `10s`) | [`supergraph[hive].poll_interval`](./supergraph#poll_interval) | + +> In cases where a configuration file (`router.config.yaml`) is used with environment variables at +> the same time, environment variables will only override the specific configuration values. + +## Additional Variables + +In addition, you may specify the following environment variables: + +| Name | Accepted Values | Description | +| ------------------------- | ---------------------------------------------------- | ---------------------------------------------------- | +| `ROUTER_CONFIG_FILE_PATH` | `string` (relative or absolute path to a local file) | Overrides the path to the router configuration file. | diff --git a/packages/web/docs/src/content/router/configuration/graphiql.mdx b/packages/web/docs/src/content/router/configuration/graphiql.mdx new file mode 100644 index 0000000000..fd59f0d9c0 --- /dev/null +++ b/packages/web/docs/src/content/router/configuration/graphiql.mdx @@ -0,0 +1,17 @@ +--- +title: 'graphiql' +--- + +# graphiql + +The `graphiql` configuration object allows you to control the GraphiQL interface. + +## Options + +### `enabled` + +- **Type:** `boolean` +- **Default:** `true` +- **Environment Variable:** `GRAPHIQL_ENABLED` + +The `enabled` property controls whether the GraphiQL interface is enabled or disabled. diff --git a/packages/web/docs/src/content/router/configuration/http.mdx b/packages/web/docs/src/content/router/configuration/http.mdx index a582e4be21..3c7429f21b 100644 --- a/packages/web/docs/src/content/router/configuration/http.mdx +++ b/packages/web/docs/src/content/router/configuration/http.mdx @@ -13,6 +13,7 @@ Router listens on for incoming GraphQL requests. - **Type:** `string` - **Default:** `"0.0.0.0"` +- **Environment Variable:** `HOST` The `host` property specifies the IP address to which the router's HTTP server will bind. @@ -25,6 +26,7 @@ The `host` property specifies the IP address to which the router's HTTP server w - **Type:** `integer` - **Default:** `4000` +- **Environment Variable:** `PORT` The `port` property specifies the network port that the router will listen on. Ensure this port is not already in use by another service on the same host. When running in a container, this is the diff --git a/packages/web/docs/src/content/router/configuration/index.mdx b/packages/web/docs/src/content/router/configuration/index.mdx index 663565d9f8..0090314a06 100644 --- a/packages/web/docs/src/content/router/configuration/index.mdx +++ b/packages/web/docs/src/content/router/configuration/index.mdx @@ -7,6 +7,9 @@ title: 'Configuration reference' You can configure Hive Router using a YAML, JSON, or TOML file (by default, `router.config.yaml`). We'll use YAML for all examples in this documentation since it's the most readable. +Some configuration variables can be overridden at runtime using +[environment variables](./environment-variables). + This page covers all the main configuration options available. Each option links to a detailed page that explains how to use that feature. diff --git a/packages/web/docs/src/content/router/configuration/log.mdx b/packages/web/docs/src/content/router/configuration/log.mdx index c7dac19619..5be7ec0004 100644 --- a/packages/web/docs/src/content/router/configuration/log.mdx +++ b/packages/web/docs/src/content/router/configuration/log.mdx @@ -16,6 +16,7 @@ You can control the verbosity, format, and filtering of the logs generated by th - **Type:** `string` - **Default:** `info` +- **Environment Variable:** `LOG_LEVEL` The `level` property controls the verbosity of the logs. By default, the router is configured to be mostly silent at the `info` level, emitting only important operational messages, warnings, and @@ -33,6 +34,7 @@ The available log levels, from most verbose to least, are: - **Type:** `string` - **Default:** `json` +- **Environment Variable:** `LOG_FORMAT` The `format` property determines the structure of the log output. @@ -47,6 +49,7 @@ The `format` property determines the structure of the log output. ### `filter` - **Type:** `string` +- **Environment Variable:** `LOG_FILTER` The `filter` property provides advanced, fine-grained control over which log messages are emitted based on their origin (e.g., a specific module within the router) and their level. This can be used diff --git a/packages/web/docs/src/content/router/configuration/supergraph.mdx b/packages/web/docs/src/content/router/configuration/supergraph.mdx index c46a08b69f..ecac07a379 100644 --- a/packages/web/docs/src/content/router/configuration/supergraph.mdx +++ b/packages/web/docs/src/content/router/configuration/supergraph.mdx @@ -24,6 +24,7 @@ Load the Supergraph schema from [Hive Console](../../schema-registry) CDN. - **Type:** `string` - **Required:** Yes +- **Environment Variable:** `HIVE_CDN_ENDPOINT` The [_Hive CDN Endpoint_](../../schema-registry/get-started/apollo-federation#cdn-access) of your target. @@ -39,6 +40,7 @@ supergraph: - **Type:** `string` - **Required:** Yes +- **Environment Variable:** `HIVE_CDN_KEY` The [_Hive CDN key/token_](../../schema-registry/management/targets#creating-a-cdn-access-token) of your target. @@ -55,6 +57,7 @@ supergraph: - **Type:** `string` - **Required:** No - **Default:** `10s` +- **Environment Variable:** `HIVE_CDN_POLL_INTERVAL` A human-readable string representing the interval at which the router should poll Hive CDN for changes. @@ -114,6 +117,7 @@ Load the schema from a local file. - **Type:** `string` - **Required:** Yes +- **Environment Variable:** `SUPERGRAPH_FILE_PATH` Path to your supergraph schema file. Can be absolute or relative to where you're running the router.