chore: move docs to mkdocs (#186)

* chore: move docs to mkdocs

* fix: add deployment section

VERSION

@@ -1 +1 @@
-0.9.14
+0.9.15

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
+```

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

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
+```

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)

docs/index.md

@@ -0,0 +1,21 @@
+# `supabase/supavisor`
+
+<p>
+<a href=""><img src="https://img.shields.io/badge/postgresql-12+-blue.svg" alt="PostgreSQL version" height="18"></a>
+<a href="https://github.com/supabase/supavisor/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License" height="18"></a>
+
+</p>
+
+---
+
+**Documentation**: <a href="https://supabase.github.io/supavisor" target="_blank">https://supabase.github.io/supavisor</a>
+
+**Source Code**: <a href="https://github.com/supabase/supavisor" target="_blank">https://github.com/supabase/supavisor</a>
+
+---
+
+## 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.

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.

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