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-split-service-mode) 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-split-service-mode) 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-split-service-mode). 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,57 @@
+---
+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 [environmental 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/)
+
+Using both environmental variables and configuration file keys is allowed and encouraged (for example, secret keys are probably best set as environmental variables). However, if duplicate configuration keys are found, environment variables 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 and use dashes (`-`). Environmental variables are identical to configuration file keys, except they are always uppercase and use underscores (`_`).
+
+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 all of Pomerium's configuration settings are set in a single configuration file. 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-split-service-mode).
 
 ![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/authenticate-internal-service-url.mdx

@@ -16,7 +16,7 @@ import TabItem from '@theme/TabItem';
 
 ## Summary
 
-**Authenticate Internal Service URL** is only required for [split-service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode) deployments where Pomerium can’t access the public [**Authenticate Service URL**](/docs/reference/authenticate-service-url).
+**Authenticate Internal Service URL** is only required for [split-service mode](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode) deployments where Pomerium can’t access the public [**Authenticate Service URL**](/docs/reference/authenticate-service-url).
 
 If included, **Authenticate Internal Service URL** will override Authenticate Service URL.
 
@@ -37,7 +37,7 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen
 
 | **Config file keys** | **Environment variables** | **Type** | **Usage** |
 | :-- | :-- | :-- | :-- |
-| `authenticate_internal_service_url` | `AUTHENTICATE_INTERNAL_SERVICE_URL` | `URL` | **required** (In [split-service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode) only) |
+| `authenticate_internal_service_url` | `AUTHENTICATE_INTERNAL_SERVICE_URL` | `URL` | **required** (In [split-service mode](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode) only) |
 
 ### Examples
 

content/docs/reference/authenticate-service-url.mdx

@@ -18,7 +18,7 @@ import TabItem from '@theme/TabItem';
 
 ## Summary
 
-**Authenticate Service URL** is the externally accessible URL for the Authenticate Service. In [split-service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode), this key is required by all services other than Databroker.
+**Authenticate Service URL** is the externally accessible URL for the Authenticate Service. In [split-service mode](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode), this key is required by all services other than Databroker.
 
 :::tip **Note:**
 

content/docs/reference/authorize-internal-service-url.mdx

@@ -16,7 +16,7 @@ import TabItem from '@theme/TabItem';
 
 ## Summary
 
-**Authorize Internal Service URL** is only required for [split-service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode) deployments where Pomerium can’t access the public [**Authorize Service URL**](/docs/reference/authorize-service-url).
+**Authorize Internal Service URL** is only required for [split-service mode](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode) deployments where Pomerium can’t access the public [**Authorize Service URL**](/docs/reference/authorize-service-url).
 
 If included, **Authorize Internal Service URL** will override Authorize Service URL.
 

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](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode) mode) |
 
 ### 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](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode) mode, 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](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode) mode) |
 
 ### Examples {#examples-grpc-insecure}
 

content/docs/reference/metrics.mdx

@@ -115,7 +115,7 @@ As of `v0.9`, Pomerium uses [Envoy](https://www.envoyproxy.io/) for the data pla
 
 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.
 
-See [Configuration & Settings](/docs/internals/configuration#all-in-one-vs-split-service-mode) for more information configuration environments.
+See [Configuration & Settings](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode) for more information 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-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).
 
 ## How to configure
 

sidebars.js

@@ -45,7 +45,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/