diff --git a/web/docs/realtime/about.md b/web/docs/realtime/about.md new file mode 100644 index 00000000000..306e5c18351 --- /dev/null +++ b/web/docs/realtime/about.md @@ -0,0 +1,44 @@ +--- +id: about +title: About +description: 'Host your own Realtime server' +--- + +## Introduction + +The easiest way to get started with Realtime is to sign up to our [Alpha](https://app.supabase.io). + +If you want to host your own Realtime server, this document will help you to get set up. You have options to host using Docker, AWS, DigitalOcean, or build from source. + +## Prerequisites + +- Postgres 10+ +- Environment variables to set: + - `DB_HOST`: defaults to `localhost` + - `DB_NAME`: defaults to `postgres` + - `DB_USER`: defaults to `postgres` + - `DB_PASSWORD`: defaults to `postgres` + - `DB_PORT`: defaults to `5432` + +## Setting Up Replication + +For us to receive the streaming data, we need the database to have a free replication slot: + +```sql +-- set the replication to "logical" +ALTER SYSTEM SET wal_level = logical; +-- We need at least one replication slot to subscribe to +ALTER SYSTEM SET max_replication_slots = 5; +-- Set up the publication for us to listen to +CREATE PUBLICATION supabase_realtime FOR ALL TABLES; +``` + +### Optional + +If you want to receive the old record (previous values) on `UPDATE` and `DELETE`, you can set the `REPLICA IDENTITY` to `FULL` like this: + +```sql +ALTER TABLE your_table SET REPLICA IDENTITY = FULL; +``` + +This has to be set for each table unfortunately. diff --git a/web/docs/realtime/aws.md b/web/docs/realtime/aws.md new file mode 100644 index 00000000000..46643f7d7c1 --- /dev/null +++ b/web/docs/realtime/aws.md @@ -0,0 +1,48 @@ +--- +id: aws +title: AWS +description: 'Host your own Realtime server' +--- + +## Quick Install + +You can use our AMI which is registered in the AWS Marketplace under the name [Supabase Realtime](https://aws.amazon.com/marketplace/pp/B089N4FH7N/). + +Once the instance is up and running, you first need to point Realtime to listen to your PostgreSQL database. First, SSH to the instance, and edit `/etc/realtime/realtime.env`: + +```bash +sudo nano /etc/realtime/realtime.env +``` + +You'll see some environment variables you need to set. If you use our [Supabase Postgres](https://aws.amazon.com/marketplace/pp/B08915TCJ2?ref_=srh_res_product_title) AMI, you simply need to set `DB_HOST` to the Postgres instance's public IP, `DB_PASSWORD` to the password you set with `\password postgres`, and `SECRET_KEY_BASE` to a randomly generated secret which you can get by running the command below: + +```bash +openssl rand -base64 48 +``` + +Now you need the Realtime service to use the newly set environment variables: + +```bash +sudo systemctl daemon-reload && sudo systemctl restart realtime +``` + +You can now disconnect from SSH. Now you should be able to visit your Realtime endpoint at `http://your_realtime_ip:4000` and receive the greeting page, which means you're ready to subscribe to changes to your database with Realtime! + +## Build from Scratch + +Make sure you have Packer [installed](https://learn.hashicorp.com/packer/getting-started/install). + +Set your AWS security credentials (you can create these [here](https://console.aws.amazon.com/iam/home?#security_credential)): + +```bash +export AWS_ACCESS_KEY=youraccesskey +export AWS_SECRET_KEY=yoursecretkey +``` + +Run Packer on `aws.json`: + +```bash +packer build aws.json +``` + +Launch an instance from the image created by Packer, and follow the steps in Quick Install. diff --git a/web/docs/realtime/digitalocean.md b/web/docs/realtime/digitalocean.md new file mode 100644 index 00000000000..c4afeffd848 --- /dev/null +++ b/web/docs/realtime/digitalocean.md @@ -0,0 +1,49 @@ +--- +id: digitalocean +title: DigitalOcean +description: 'Host your own Realtime server' +--- + +## Quick Install + +You can use our droplet which is registered in the DigitalOcean Marketplace under the name [Supabase Realtime](https://marketplace.digitalocean.com/apps/supabase-realtime). + +Before we start, this droplet enables UFW that allows port `22` for SSH, port `5432` for PostgreSQL, and port `4000` for serving Supabase Realtime subscriptions. If you want to use different ports for your PostgreSQL database or Realtime, you have to configure UFW to allow those ports. Otherwise, read on! + +Once the droplet is up and running, you first need to point Realtime to listen to your PostgreSQL database. First, SSH to the droplet instance, and edit `/etc/realtime/realtime.env`: + +```bash +nano /etc/realtime/realtime.env +``` + +You'll see some environment variables you will need to set. If you are using our [Supabase Postgres](https://marketplace.digitalocean.com/apps/supabase-postgres) droplet, you simply need to set `DB_HOST` to the Postgres droplet's public IP, `DB_PASSWORD` to the password you set with `\password postgres`, and `SECRET_KEY_BASE` to a randomly generated secret which you can get by running the command below: + +```bash +openssl rand -base64 48 +``` + +Now you need the Realtime service to use the newly set environment variables: + +```bash +systemctl daemon-reload && systemctl restart realtime +``` + +You can now disconnect from SSH. Now you should be able to visit your Realtime endpoint at `http://your_realtime_droplet_ip:4000` and receive the greeting page, which means you're ready to subscribe to changes to your database with Realtime! + +## Build from Scratch + +Make sure you have Packer [installed](https://learn.hashicorp.com/packer/getting-started/install). + +Set `DO_API_TOKEN` to a personal access token (you can create one by following [these steps](https://www.digitalocean.com/docs/apis-clis/api/create-personal-access-token/)): + +```bash +export DO_API_TOKEN=youraccesstoken +``` + +Run Packer on `do.json`: + +```bash +packer build do.json +``` + +Launch an instance from the image created by Packer, and follow the steps in Quick Install. diff --git a/web/docs/realtime/docker.md b/web/docs/realtime/docker.md new file mode 100644 index 00000000000..0f0a0acddd7 --- /dev/null +++ b/web/docs/realtime/docker.md @@ -0,0 +1,44 @@ +--- +id: docker +title: Docker +description: 'Host your own Realtime server' +--- + +Make sure you have Docker [installed](https://docs.docker.com/get-docker/). + +## Quick Install + +The image is available in [Docker Hub](https://hub.docker.com/r/supabase/realtime) under the name `supabase/realtime`. + +You can use the [docker-compose file](https://github.com/supabase/realtime/blob/master/docker-compose.dev.yml) in this repository as a starting point. Note that this already includes a Postgres database image, so you don't have to set one up yourself. + +Fill up the environment variables as appropriate, and then run the image: + +```bash +docker-compose up +``` + +## Build from Scratch + +Build the image: + +```bash +docker build --tag foo . +``` + +Run the image: + +```bash +# Update the environment variables to point to your own database +docker run --rm \ + -e DB_HOST=host.docker.internal \ + -e DB_NAME=postgres \ + -e DB_USER=postgres \ + -e DB_PASSWORD=postgres \ + -e DB_PORT=5432 \ + -e PORT=4000 \ + -e HOSTNAME=localhost \ + -e SECRET_KEY_BASE=SOMETHING_SUPER_SECRET \ + -p 4000:4000 \ + foo +``` diff --git a/web/docs/realtime/install.mdx b/web/docs/realtime/install.mdx deleted file mode 100644 index ca8e0da4c9f..00000000000 --- a/web/docs/realtime/install.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -id: realtime-install -title: Install Realtime -description: 'Host your own realtime server' ---- - -> Status: DRAFT - -## Introduction - -The easiest way to get started with Realtime is to sign up to our [Alpha](https://app.supabase.io). - -If you want to host your own realtime server, this document will help you to get set up. - -## Pre-requisites - -- Postgres 10+ - -## What you will need - -- `DB_HOST`: defaults to `localhost` -- `DB_NAME`: defaults to `postgres` -- `DB_USER`: defaults to `postgres` -- `DB_PASSWORD`: defaults to `postgres` -- `DB_PORT`: defaults to `5432` - - -## Setting up replication - -For us to receive the streaming data, we need the database to have a free replication slot: - -```sql -ALTER SYSTEM SET wal_level = logical; -- set the replication to "logical" -ALTER SYSTEM SET max_replication_slots = 5; -- We need at least one replication slot to subscribe to -CREATE PUBLICATION supabase_realtime FOR ALL TABLES; -- Set up the publication for us to listen to -``` - -### Optional - -If you want to receive the old record (previous values) on `UPDATE` and `DELETE`, you can set the `REPLICA IDENTITY` to `FULL` like this: - -```sql -ALTER TABLE your_table SET REPLICA IDENTITY = FULL; -``` - -This has to be set for each table unfortunately. diff --git a/web/docs/realtime/source.md b/web/docs/realtime/source.md new file mode 100644 index 00000000000..8fc8832e310 --- /dev/null +++ b/web/docs/realtime/source.md @@ -0,0 +1,41 @@ +--- +id: source +title: Building from Source +description: 'Host your own Realtime server' +--- + +Make sure you have Elixir [installed](https://elixir-lang.org/install.html). + +Make sure you are in the right directory: + +```bash +cd server +``` + +Install dependencies: + +```bash +mix local.hex --force +mix local.rebar --force +mix deps.get +``` + +Create the release: + +```bash +MIX_ENV=prod mix release +``` + +Start the release (set the environment variables as appropriate): + +```bash +SECRET_KEY_BASE=SOMETHING_SECRET \ +PORT=4000 \ +HOSTNAME=localhost \ +DB_USER=postgres \ +DB_HOST=localhost \ +DB_PASSWORD=postgres \ +DB_NAME=postgres \ +DB_PORT=5432 \ +_build/prod/rel/realtime/bin/realtime start +``` diff --git a/web/sidebars.js b/web/sidebars.js index 0b533db24b8..906e2d97815 100755 --- a/web/sidebars.js +++ b/web/sidebars.js @@ -18,7 +18,13 @@ module.exports = { 'library/stored-procedures', ], // Guides: ['guides/examples'], - Realtime: ['realtime/realtime-install'], + Realtime: [ + 'realtime/about', + 'realtime/docker', + 'realtime/aws', + 'realtime/digitalocean', + 'realtime/source', + ], Postgres: ['postgres/postgres-intro'], 'See Also': ['guides/examples', 'pricing', 'support'], Handbook: ['handbook/introduction', 'handbook/contributing'],