Updates configuration page

content/docs/capabilities/high-availability.mdx

@@ -10,7 +10,7 @@ import InstallMkcert from '@site/content/_install-mkcert.md';
 
 Pomerium is designed to be run in two modes: All-In-One or Split Service. These modes are not mutually exclusive, meaning you can run one or multiple instances of Pomerium in all-in-one mode, and spin up additional instances for specific components as needed.
 
-Each instance of Pomerium runs in all-in-one mode unless specified to run as a specific component by the `services` key. See [All-In-One vs. Split Service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode) for more details.
+Each instance of Pomerium runs in all-in-one mode unless specified to run as a specific component by the `services` key. See [All-in-One vs. Split Service mode](/docs/core/configuration#all-in-one-and-split-service-modes) for more details.
 
 :::caution
 

content/docs/capabilities/mtls-services.mdx

@@ -43,7 +43,7 @@ To provide a general explanation, in this guide you will use [mkcert](https://gi
 
 To complete this proof-of-concept guide:
 
-- Run Pomerium in [all-in-one mode](/docs/internals/configuration#all-in-one-vs-split-service-mode) as a system service with a configuration file in the [standard location](/docs/core/from-source#configure)
+- Run Pomerium in [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes) as a system service with a configuration file in the [standard location](/docs/core/from-source#configure)
 - Configure an [identity provider](/docs/identity-providers) (IdP) to communicate with your Pomerium instance
 - Run all commands on the same host (You may have to move files or adjust paths and commands to match a different configuration)
 - Install [`mkcert`](https://github.com/FiloSottile/mkcert) to generate self-signed certificates and a root Certificate Authority (CA) (`mkcert` will take the place of your trusted certificate tooling solution)

content/docs/concepts/mutual-auth.md

@@ -28,7 +28,7 @@ This guide covers the following mutual authentication methods with Pomerium:
 
 This section provides examples of mutual authentication methods you can implement with Pomerium.
 
-Each example diagrams Pomerium as a single service, as it is in [all-in-one mode](/docs/internals/configuration#all-in-one-vs-split-service-mode). This is the version provided by our [binaries] and in our Docker-based [Quickstart].
+Each example diagrams Pomerium as a single service, as it is in [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes). This is the version provided by our [binaries] and in our Docker-based [Quickstart].
 
 ### Basic Pomerium installation
 

content/docs/core/configuration.md

@@ -0,0 +1,59 @@
+---
+title: Configuration
+description: This page discusses configuration settings for Pomerium Core.
+keywords: [core configuration]
+sidebar_label: Configuration
+---
+
+# Configuration
+
+You can configure Pomerium using either a configuration file or [environment variables](https://en.wikipedia.org/wiki/Environment_variable). If using a configuration file, the following languages are supported:
+
+- [YAML](https://yaml.org/)
+- [JSON](https://www.json.org/json-en.html)
+- [TOML](https://toml.io/en/)
+
+(Our documentation always assumes a YAML configuration file.)
+
+You can use both environment variables and a configuration file. If a particular option is set using both an environment variable and a config file key, the environment variable will take precedence.
+
+:::tip
+
+Pomerium can hot-reload route configuration details, authorization policy, certificates, and other proxy settings.
+
+:::
+
+### Configuration syntax
+
+Both configuration file keys and environment variables are case sensitive.
+
+Configuration file keys are always lowercase. Environment variables are identical to configuration file keys, except they are always uppercase.
+
+See the [Reference](/docs/reference) page for a comprehensive list of Pomerium's configuration settings.
+
+## All-in-One and Split-Service modes
+
+You can configure Pomerium using either All-in-One mode or Split-Service mode.
+
+### All-in-One mode
+
+All-in-One mode means a single Pomerium process runs all of the [four logical services](/docs/internals/architecture#component-level). You can use All-in-One mode when running Pomerium:
+
+- As a single system service or container, or
+- In a distributed environment where there are multiple processes that each handle separate [Pomerium services](/docs/internals/architecture#component-level).
+
+All-in-One mode is the default configuration mode, and the easiest way to configure Pomerium.
+
+### Split-Service mode
+
+Alternately, you can create individual configuration files (or sets of environment variables) for each Pomerium service. In Split-Service mode, each configuration file (or set of environment variables) defines which service a process will run by using the [service mode](/docs/reference/service-mode) key.
+
+:::tip Our recommendation
+
+We recommend All-in-One mode to configure Pomerium for the following reasons:
+
+- **Reduce complexity**: All-in-One mode reduces the complexity of managing configuration. A single configuration file means there is one source of truth.
+- **Secure communication**: Pomerium services communicate internally. Splitting up services requires securing these endpoints and configuring DNS records for each service.
+- **Scaling**: All-in-One deployments scale for better performance. All URLs point at the same Pomerium service instance.
+
+:::

content/docs/internals/architecture.md

@@ -60,7 +60,7 @@ The points below outline the Databroker’s role in the request and session life
 
 In production deployments, it is recommended that you deploy each component [separately](/docs/reference/service-mode). This allows you to limit external attack surface, as well as scale and manage the services independently.
 
-In test deployments, all four components may run from a [single binary and configuration](/docs/internals/configuration#all-in-one-vs-split-service-mode).
+In test deployments, all four components may run from a [single binary and configuration](/docs/core/configuration#all-in-one-and-split-service-modes).
 
 ![pomerium architecture diagram](./img/architecture/pomerium-container-context-stateless-authn.svg)
 

content/docs/k8s/ingress.md

@@ -23,7 +23,7 @@ The [Pomerium Kubernetes Ingress Controller](https://github.com/pomerium/ingress
 
 Pomerium’s Ingress Controller for Kubernetes enables you to dynamically provision routes from Ingress resources and set authorization policy on those routes with Ingress annotations. By defining routes as Ingress resources in the Kubernetes API, you can easily create and remove those routes from your Pomerium configuration.
 
-If you've tested Pomerium using the [all-in-one binary](/docs/core), you're probably familiar with configuring routes in Pomerium's [`config.yaml`](/docs/internals/configuration) file. When using the Pomerium Ingress Controller, each route is defined as an Ingress resource in the Kubernetes API.
+If you've tested Pomerium using the [all-in-one binary](/docs/core), you're probably familiar with configuring routes in Pomerium's [`config.yaml`](/docs/core/configuration) file. When using the Pomerium Ingress Controller, each route is defined as an Ingress resource in the Kubernetes API.
 
 This document shows you how to configure an Ingress resource that’s compatible with the Pomerium Ingress Controller.
 

content/docs/reference.mdx

@@ -8,6 +8,6 @@ pagination_next: null
 
 import ReferenceTable from '../../src/components/ReferenceTable';
 
-For details on how to set configuration settings see the [configuration internals](/docs/internals/configuration) page.
+For details on how to set configuration settings see the [configuration](/docs/core/configuration) page.
 
 <ReferenceTable />

content/docs/reference/grpc.mdx

@@ -31,7 +31,7 @@ This reference covers all of Pomerium's **gRPC Settings**:
 
 | **Config file keys** | **Environment variables** | **Type** | **Default** |
 | :-- | :-- | :-- | :-- |
-| `grpc_address` | `GRPC_ADDRESS` | `string` | `:443` (`:5443` if in [all-in-one](/docs/internals/configuration#all-in-one-vs-split-service-mode) mode) |
+| `grpc_address` | `GRPC_ADDRESS` | `string` | `:443` (`:5443` if in [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes)) |
 
 ### Examples {#examples-grpc-address}
 
@@ -130,7 +130,7 @@ Kubernetes does not support **gRPC Client Timeout**
 
 ## gRPC Insecure {#grpc-insecure}
 
-**gRPC Insecure** disables transport security for gRPC communication. If running in [all-in-one](/docs/internals/configuration#all-in-one-vs-split-service-mode) mode, defaults to true as communication will run over localhost's own socket.
+**gRPC Insecure** disables transport security for gRPC communication. If running in [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes), defaults to true as communication will run over localhost's own socket.
 
 ### How to configure {#how-to-configure-grpc-insecure}
 
@@ -139,7 +139,7 @@ Kubernetes does not support **gRPC Client Timeout**
 
 | **Config file keys** | **Environment variables** | **Type** | **Default** |
 | :-- | :-- | :-- | :-- |
-| `grpc_insecure` | `GRPC_INSECURE` | `boolean` | `true` (If in [all-in-one](/docs/internals/configuration#all-in-one-vs-split-service-mode) mode) |
+| `grpc_insecure` | `GRPC_INSECURE` | `boolean` | `true` (If in [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes)) |
 
 ### Examples {#examples-grpc-insecure}
 

content/docs/reference/metrics.mdx

@@ -113,9 +113,9 @@ Identity manager metrics have a `pomerium_identity_manager` prefix.
 
 As of `v0.9`, Pomerium uses [Envoy](https://www.envoyproxy.io/) for the data plane. As such, proxy related metrics are sourced from Envoy, and use Envoy's internal [stats data model](https://www.envoyproxy.io/docs/envoy/latest/operations/stats_overview). Please see Envoy's documentation for information about specific metrics.
 
-All metrics coming from Envoy will be labeled with `service="pomerium"` or `service="pomerium-proxy"`, depending if you're running all-in-one or distributed service mode and have `pomerium` prefix added to the standard envoy metric name.
+All metrics coming from Envoy will be labeled with `service="pomerium"` or `service="pomerium-proxy"`, depending if you're running all-in-one or split-service mode and have `pomerium` prefix added to the standard envoy metric name.
 
-See [Configuration & Settings](/docs/internals/configuration#all-in-one-vs-split-service-mode) for more information configuration environments.
+See [All-in-One and Split-Service modes](/docs/core/configuration#all-in-one-and-split-service-modes) for more information about configuration environments.
 
 ## Metrics Basic Authentication {#metrics-basic-authentication}
 

content/docs/reference/service-mode.mdx

@@ -18,7 +18,7 @@ import TabItem from '@theme/TabItem';
 
 ## Summary
 
-**Service Mode** sets which service(s) to run. If testing, you may want to set to `all` and run Pomerium in [all-in-one mode](/docs/internals/configuration#all-in-one-vs-split-service-mode). In production, you'll likely want to spin up several instances of each service mode for [high availability](/docs/capabilities/high-availability).
+**Service Mode** sets which service(s) to run. If testing, you may want to set to `all` and run Pomerium in [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes). In production, you'll likely want to spin up several instances of each service mode for [high availability](/docs/capabilities/high-availability).
 
 ## How to configure
 

content/docs/reference/service-urls.md

@@ -44,7 +44,7 @@ If not set, Pomerium will use the [Hosted Authenticate Service](/docs/capabiliti
 
 If you prefer to use your own [identity provider](/docs/identity-providers), you'll need to set an authenticate service URL, and you will need this URL when configuring your identity provider client's OAuth callback URL.
 
-If Pomerium is running in [split-service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode), each Pomerium service requires the authenticate service URL in its configuration.
+If Pomerium is running in [split-service mode](/docs/core/configuration#all-in-one-and-split-service-modes), each Pomerium service requires the authenticate service URL in its configuration.
 
 :::info
 
@@ -233,8 +233,8 @@ The **Databroker Service URL** settings points to a databroker which is responsi
 
 | **Config file keys** | **Environment variables** | **Type** | **Default** |
 | :-- | :-- | :-- | :-- |
-| `databroker_service_url` | `DATABROKER_SERVICE_URL` | `URL` | `http://localhost:5443` (In [all-in-one mode](/docs/internals/configuration#all-in-one-vs-split-service-mode)) |
-| `databroker_service_urls` | `DATABROKER_SERVICE_URLS` | `URL` | `http://localhost:5443` (In [all-in-one mode](/docs/internals/configuration#all-in-one-vs-split-service-mode)) |
+| `databroker_service_url` | `DATABROKER_SERVICE_URL` | `URL` | `http://localhost:5443` (In [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes)) |
+| `databroker_service_urls` | `DATABROKER_SERVICE_URLS` | `URL` | `http://localhost:5443` (In [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes)) |
 
 #### Examples {#databroker-service-url-examples}
 
@@ -272,8 +272,8 @@ The **Databroker Internal Service URL** overrides [`databroker_service_url`](/do
 
 | **Config file keys** | **Environment variables** | **Type** | **Default** |
 | :-- | :-- | :-- | :-- |
-| `databroker_internal_service_url` | `DATABROKER_INTERNAL_SERVICE_URL` | `URL` | `http://localhost:5443` (In all-in-one mode) |
-| `databroker_internal_service_urls` | `DATABROKER_INTERNAL_SERVICE_URLS` | `URL` | `http://localhost:5443` (In all-in-one mode) |
+| `databroker_internal_service_url` | `DATABROKER_INTERNAL_SERVICE_URL` | `URL` | `http://localhost:5443` (In [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes)) |
+| `databroker_internal_service_urls` | `DATABROKER_INTERNAL_SERVICE_URLS` | `URL` | `http://localhost:5443` (In [all-in-one mode](/docs/core/configuration#all-in-one-and-split-service-modes)) |
 
 #### Examples {#databroker-internal-service-url-examples}
 

sidebars.js

@@ -49,7 +49,14 @@ const sidebars = {
       type: 'category',
       label: 'Pomerium Core',
       link: {type: 'doc', id: 'docs/core'},
-      items: [{type: 'autogenerated', dirName: 'docs/core'}],
+      items: [
+        'docs/core/quickstart',
+        'docs/core/configuration',
+        'docs/core/changelog',
+        'docs/core/upgrading',
+        'docs/core/from-source',
+        'docs/core/binary',
+      ],
     },
     {
       type: 'category',

static/_redirects

@@ -5,7 +5,7 @@
 /docs/releases /docs/deploy/releases
 /docs/deploy/releases /docs/community/contributing
 
-# Configuration & Settings Reference (reference links redirect correctly)
+# Configuration & Settings Reference
 /docs/reference/reference /docs/reference
 /docs/reference/reference.html /docs/reference
 /docs/configuration/ /docs/reference
@@ -25,6 +25,7 @@
 /docs/security /docs/internals/security
 /docs/security.html /docs/internals/security
 /docs/community/security.html /docs/internals/security
+/docs/internals/configuration /docs/core/configuration
 
 # Guide and examples links
 /guide/ /docs/quick-start/