Skip to content

docs: add environment variables documentation #659

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
v0idpwn merged 5 commits into from
Jun 13, 2025
Merged

docs: add environment variables documentation #659

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d955207
docs: add environment variables documentation
abc3 Jun 12, 2025
07aba76
clarify PROXY_PORT
abc3 Jun 12, 2025
0e4f836
docs: update add release/testing configuration sections
abc3 Jun 12, 2025
52dba58
Merge branch 'main' into docs/envs-description
abc3 Jun 12, 2025
8bad72c
Merge branch 'main' into docs/envs-description
v0idpwn Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ supported ([todo](#future-work)).
## Docs

- [Installation and usage](https://supabase.github.io/supavisor/development/installation/)
- [Environment Variables Documentation](https://supabase.github.io/supavisor/configuration/env/)
- [Metrics](https://supabase.github.io/supavisor/monitoring/metrics/)

## Features
Expand Down
132 changes: 132 additions & 0 deletions docs/configuration/env.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
# Supavisor Environment Variables

This document provides a categorized list of all environment variables used in Supavisor, including connection pool settings, clustering, Phoenix API server, and logging configuration.

## Table of Contents

1. [Core Configuration](#1-core-configuration)
2. [Management API Configuration](#2-management-api-configuration)
- [Phoenix HTTP Server](#phoenix-http-server)
- [Security](#security)
- [Metrics](#metrics)
- [Logging](#logging)
3. [Metadata Database Configuration](#3-metadata-database-configuration)
4. [Node and Clustering Configuration](#4-node-and-clustering-configuration)
5. [Fly.io Deployment Configuration](#5-flyio-deployment-configuration)
6. [Release Configuration](#6-release-configuration)
7. [Testing Configuration](#7-testing-configuration)

---

## 1. Core Configuration

| Variable | Description | Default Value | Required |
| ----------------------------- | ------------------------------- | ------------- | -------- |
| `PROXY_PORT_TRANSACTION` | Transaction pool port | `6543` | No |
| `PROXY_PORT_SESSION` | Session pool port | `5432` | No |
| `PROXY_PORT` | Internal proxy port | `5412` | No |
| `RECONNECT_ON_DB_CLOSE` | Enable reconnection on close | `false` | No |
| `RECONNECT_RETRIES` | Number of reconnection attempts | `5` | No |
| `SUBSCRIBE_RETRIES` | Number of subscription retries | `20` | No |
| `SWITCH_ACTIVE_COUNT` | Switch active connection count | `100` | No |
| `GLOBAL_UPSTREAM_CA_PATH` | Upstream CA certificate path | - | No |
| `GLOBAL_DOWNSTREAM_CERT_PATH` | Downstream certificate path | - | No |
| `GLOBAL_DOWNSTREAM_KEY_PATH` | Downstream private key path | - | No |
| `LOCAL_PROXY_MULTIPLIER` | Local proxy multiplier value | `20` | No |

---

## 2. Management API Configuration

### Phoenix HTTP Server

| Variable | Description | Default Value | Required |
| ----------------- | ---------------------------- | ------------- | ------------- |
| `PORT` | Server port | `4000` | No |
| `MAX_CONNECTIONS` | Maximum connections allowed | `1000` | No |
| `NUM_ACCEPTORS` | Number of acceptor processes | `100` | No |
| `ADDR_TYPE` | Socket address type | `inet` | No |
| `SECRET_KEY_BASE` | Phoenix endpoint secret key | - | Yes (in prod) |

### Security

| Variable | Description | Default Value | Required |
| ------------------------- | ---------------------------------------------- | ------------- | -------------------- |
| `JWT_CLAIM_VALIDATORS` | JWT claim validators configuration | `{}` | No |
| `API_JWT_SECRET` | Secret for API JWT authentication | - | No |
| `METRICS_JWT_SECRET` | Secret for metrics JWT authentication | - | No |
| `API_TOKEN_BLOCKLIST` | Comma-separated list of blocked API tokens | - | No |
| `METRICS_TOKEN_BLOCKLIST` | Comma-separated list of blocked metrics tokens | - | No |
| `VAULT_ENC_KEY` | Encryption key for Vault | - | Yes (if using Vault) |

### Metrics

| Variable | Description | Default Value | Required |
| ------------------ | --------------------------------------- | ------------- | -------- |
| `METRICS_DISABLED` | Disable metrics collection | `false` | No |
| `PROM_POLL_RATE` | Prometheus polling rate in milliseconds | `15000` | No |

### Logging

| Variable | Description | Default Value | Required |
| -------------------------------- | ----------------------- | ------------- | ----------------------- |
| `SUPAVISOR_LOG_FILE_PATH` | Path to log file | - | No |
| `SUPAVISOR_LOG_FORMAT` | Log format (json/text) | `text` | No |
| `SUPAVISOR_ACCESS_LOG_FILE_PATH` | Path to access log file | - | No |
| `LOGS_ENGINE` | Logging engine to use | - | No |
| `LOGFLARE_API_KEY` | Logflare API key | - | Yes (if using Logflare) |
| `LOGFLARE_SOURCE_ID` | Logflare source ID | - | Yes (if using Logflare) |

---

## 3. Metadata Database Configuration

| Variable | Description | Default Value | Required |
| ------------------------- | ------------------------------------- | -------------------------------------------------- | -------- |
| `DATABASE_URL` | Connection URL | `ecto://postgres:postgres@localhost:6432/postgres` | No |
| `DB_POOL_SIZE` | Connection pool size | `25` | No |
| `SUPAVISOR_DB_IP_VERSION` | IP version for connection (ipv4/ipv6) | `ipv4` | No |

---

## 4. Node and Clustering Configuration

| Variable | Description | Default Value | Required |
| ------------------- | --------------------------------------------------------------------------- | ------------- | -------- |
| `NODE_NAME` | Base name for the node | `supavisor` | No |
| `NODE_IP` | Node host IP address | `127.0.0.1` | No |
| `AVAILABILITY_ZONE` | Current availability zone | - | No |
| `REGION` | Current region (falls back to `FLY_REGION` if not set) | - | No |
| `DNS_POLL` | DNS polling configuration for clustering | - | No |
| `CLUSTER_NODES` | Comma-separated list of cluster nodes | - | No |
| `CLUSTER_POSTGRES` | Enable PostgreSQL-based clustering (uses `DATABASE_URL` for node discovery) | - | No |
| `CLUSTER_ID` | Cluster identifier | - | No |
| `LOCATION_ID` | Location identifier | - | No |
| `LOCATION_KEY` | Location key (falls back to region if not set) | - | No |
| `INSTANCE_ID` | Instance identifier | - | No |

---

## 5. Fly.io Deployment Configuration

| Variable | Description | Default Value | Required |
| -------------- | ---------------- | ------------- | -------- |
| `FLY_APP_NAME` | Application name | - | No |
| `FLY_REGION` | Region | - | No |
| `FLY_ALLOC_ID` | Allocation ID | - | No |

## 6. Release Configuration

| Variable | Description | Default Value | Required |
| --------------------------- | --------------------------------------------------- | ------------- | -------- |
| `INCLUDE_ERTS` | Whether to include ERTS in the release | `true` | No |
| `RELEASE_COOKIE` | Release cookie for distributed Erlang | Random value | No |
| `UPGRADE_FROM` | Version to upgrade from during hot upgrades | - | No |
| `DEBUG_LOAD_RUNTIME_CONFIG` | Load runtime config from config/runtime.exs if true | - | No |
| `RELEASE_ROOT` | Root directory of the release | - | No |

## 7. Testing Configuration

| Variable | Description | Default Value | Required |
| ----------- | ---------------------------- | ------------- | -------- |
| `TEST_LOGS` | Controls test logging output | `all` | No |
1 change: 1 addition & 0 deletions mkdocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ nav:
- Overview: "connecting/overview.md"
- Authentication: "connecting/authentication.md"
- Configuration:
- Environment Variables: "configuration/env.md"
- Tenants: "configuration/tenants.md"
- Users: "configuration/users.md"
- Pool Modes: "configuration/pool_modes.md"
Expand Down
Loading