From d78c7f644138689f1ceb40431144cd47e0b1c537 Mon Sep 17 00:00:00 2001 From: Chase Granberry Date: Mon, 16 Oct 2023 08:26:57 -0700 Subject: [PATCH] chore: move docs to mkdocs (#186) * chore: move docs to mkdocs * fix: add deployment section --- VERSION | 2 +- docs/connecting.md | 37 +++++++++++++++++++ docs/deployment/fly.md | 41 +++++++++++++++++++++ docs/development/installation.md | 13 +++++++ docs/development/setup.md | 60 +++++++++++++++++++++++++++++++ docs/images/favicon.ico | Bin 0 -> 15086 bytes docs/index.md | 21 +++++++++++ docs/metrics.md | 31 ++++++++++++++++ mkdocs.yaml | 43 ++++++++++++++++++++++ 9 files changed, 247 insertions(+), 1 deletion(-) create mode 100644 docs/connecting.md create mode 100644 docs/deployment/fly.md create mode 100644 docs/development/installation.md create mode 100644 docs/development/setup.md create mode 100644 docs/images/favicon.ico create mode 100644 docs/index.md create mode 100644 docs/metrics.md create mode 100644 mkdocs.yaml diff --git a/VERSION b/VERSION index 6d44d227..5d11b147 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.9.14 +0.9.15 diff --git a/docs/connecting.md b/docs/connecting.md new file mode 100644 index 00000000..dacb21ca --- /dev/null +++ b/docs/connecting.md @@ -0,0 +1,37 @@ +To connect to a tenant database Supavisor needs to look up the tenant with an `external_id`. + +You can connect to Supavisor just like you connect to Postgres except we need to include the `external_id` in the connection string. + +Supavisor parses the `external_id` from a connection in one three ways: + +- The username +- Server name identification +- `options` parameters + +> 📘 Examples +> +> In the following examples our `external_id` is `dev_tenant`. + +## Username + +Include the `external_id` in the username. The `external_id` is found after the `.` in the username: + +``` +psql postgresql://postgres.dev_tenant:postgres@localhost:6543/postgres +``` + +## Server name indication + +The subdomain of the SNI from the TLS handshake: + +``` +dev_tenant.supabase.co +``` + +## Options parameters + +Include the `external_id` as the `reference` in the `options` parameters: + +``` +psql postgresql://postgres:postgres@localhost:6543/postgres&options=reference%3Ddev_tenant +``` diff --git a/docs/deployment/fly.md b/docs/deployment/fly.md new file mode 100644 index 00000000..668c4b04 --- /dev/null +++ b/docs/deployment/fly.md @@ -0,0 +1,41 @@ +The `toml.yaml` file should be in the `deploy/fly` directory of Supavisor. + +Type the following command in your terminal: + +```bash +fly launch +``` + +Choose a name for your app when prompted, then answer "yes" to the following question: + +```bash +Would you like to copy its configuration to the new app? (y/N) +``` + +Next, select an organization and choose a region. You don't need to deploy the app yet. + +Since the pooler uses an additional port (7654) for the PostgreSQL protocol, you need to reserve an IP address: + +```bash +fly ips allocate-v4 +``` + +Set your app's secrets by running the following command: + +```bash +fly secrets set DATABASE_URL="ecto://postgres:postgres@localhost:6432/postgres" \ +VAULT_ENC_KEY="some_vault_secret" \ +API_JWT_SECRET="some_api_secret" \ +METRICS_JWT_SECRET="some_metrics_secret" \ +SECRET_KEY_BASE="some_kb_secret" +``` + +Replace the example values with your actual secrets. + +Finally, deploy your app using the following command: + +```bash +fly deploy +``` + +This will deploy your app on Fly.io diff --git a/docs/development/installation.md b/docs/development/installation.md new file mode 100644 index 00000000..0c773a1b --- /dev/null +++ b/docs/development/installation.md @@ -0,0 +1,13 @@ +Before starting, set up the database where Supavisor will store tenants' data. The following command will pull a Docker image with PostgreSQL 14 and run it on port 6432: + +``` +docker-compose -f ./docker-compose.db.yml up +``` + +> `Supavisor` stores tables in the `supavisor` schema. The schema should be automatically created by the `dev/postgres/00-setup.sql` file. If you encounter issues with migrations, ensure that this schema exists. + +Next, get dependencies and apply migrations: + +``` +mix deps.get && mix ecto.migrate --prefix _supavisor --log-migrator-sql +``` diff --git a/docs/development/setup.md b/docs/development/setup.md new file mode 100644 index 00000000..b696f229 --- /dev/null +++ b/docs/development/setup.md @@ -0,0 +1,60 @@ +Launch the Supavisor application: + +``` +make dev +``` + +You need to add tenants to the database. For example, the following request will add the `dev_tenant` with credentials to the database set up earlier. + +## Add/update tenant + +```bash +curl -X PUT \ + 'http://localhost:4000/api/tenants/dev_tenant' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNjQ1MTkyODI0LCJleHAiOjE5NjA3Njg4MjR9.M9jrxyvPLkUxWgOYSf5dNdJ8v_eRrq810ShFRT8N-6M' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "tenant": { + "db_host": "localhost", + "db_port": 6432, + "db_database": "postgres", + "ip_version": "auto", // "auto" | v4 | v6 + "require_user": true, // true | false + "upstream_ssl": true, // true | false, + "enforce_ssl": false, // true | false, + "upstream_verify": "peer", // "none" | "peer" + "upstream_tls_ca": "-----BEGIN CERTIFICATE-----\nblalblalblablalblalblaba\n-----END CERTIFICATE-----\n", // "" + "users": [ + { + "db_user": "postgres", + "db_password": "postgres", + "pool_size": 20, + "mode_type": "transaction", + "pool_checkout_timeout": 100 + } + ] + } +}' +``` + +Now, it's possible to connect through the proxy. By default, Supavisor uses port `6543` for transaction mode and `5432` for session mode: + +``` +psql postgresql://postgres.dev_tenant:postgres@localhost:6543/postgres +``` + +> :warning: The tenant's ID is incorporated into the username and separated by the `.` symbol. For instance, for the username `some_username` belonging to the tenant `some_tenant`, the modified username will be `some_username.some_tenant`. This approach enables the system to support multi-tenancy on a single IP address. + +## Delete tenant + +To delete a tenant, send the following request: + +```bash +curl -X DELETE \ + 'http://localhost:4000/api/tenants/dev_tenant' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNjQ1MTkyODI0LCJleHAiOjE5NjA3Njg4MjR9.M9jrxyvPLkUxWgOYSf5dNdJ8v_eRrq810ShFRT8N-6M' +``` + +API documentation can be found at [http://localhost:4000/swaggerui](http://localhost:4000/swaggerui) diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..d3fca2acb10d86d7ff179fe66fa372dabeb21c91 GIT binary patch literal 15086 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 +PostgreSQL version +License + +

+ +--- + +**Documentation**: https://supabase.github.io/supavisor + +**Source Code**: https://github.com/supabase/supavisor + +--- + +## Overview + +Supavisor is an open source scalable connection pooler for Postgres. + +Review the [readme](https://github.com/supabase/supavisor/blob/main/README.md) for a detailed overview. diff --git a/docs/metrics.md b/docs/metrics.md new file mode 100644 index 00000000..1e3c2caf --- /dev/null +++ b/docs/metrics.md @@ -0,0 +1,31 @@ +The metrics feature provides a range of metrics in the Prometheus format. The main modules involved in this implementation are: + +- `Supavisor.Monitoring.PromEx` +- `Supavisor.PromEx.Plugins.OsMon` +- `Supavisor.PromEx.Plugins.Tenant` +- `Supavisor.Monitoring.Telem` + +## Metrics exposed + +The exposed metrics include the following: + +- Application +- BEAM +- Phoenix +- Ecto +- System monitoring metrics: + - CPU utilization + - RAM usage + - Load average (LA) +- Pool checkout queue time +- Number of connected clients +- Query duration and query counts +- Network usage for client sockets and database sockets + +## Usage + +To use the metrics feature, send an HTTP request to the `/metrics` endpoint. The endpoint is secured using Bearer authentication, which requires a JSON Web Token (JWT) generated using the `METRICS_JWT_SECRET` environment variable. Make sure to set this environment variable with a secure secret key. + +When a node receives a request for metrics, it polls all nodes in the cluster, accumulates their metrics, and appends service tags such as region and host. To generate a valid JWT, use a library or tool that supports JWT creation with the HS256 algorithm and the `METRICS_JWT_SECRET` as the secret key. + +Remember to keep the `METRICS_JWT_SECRET` secure and only share it with authorized personnel who require access to the metrics endpoint. diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 00000000..a2d96117 --- /dev/null +++ b/mkdocs.yaml @@ -0,0 +1,43 @@ +site_name: supavisor +site_url: https://supabase.github.io/supavisor +site_description: A cloud native multi-tenant connection pooler for Postgres + +repo_name: supabase/supavisor +repo_url: https://github.com/supabase/supavisor + +nav: + - Welcome: 'index.md' + - Development: + - Installation: 'development/installation.md' + - Setup: 'development/setup.md' + - Deployment: + - Deploy with Fly.io: 'deployment/fly.md' + - Connecting: 'connecting.md' + - Metrics: 'metrics.md' + +theme: + name: 'material' + favicon: 'images/favicon.ico' + logo: 'images/favicon.ico' + homepage: https://supabase.github.io/supavisor + features: + - navigation.expand + palette: + primary: black + accent: light green + +markdown_extensions: + - pymdownx.highlight: + linenums: true + guess_lang: false + use_pygments: true + pygments_style: default + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.snippets + - pymdownx.tasklist + - admonition + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg \ No newline at end of file