Skip to content

Align Supabase docs with upstream self-hosting #290

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

Draft
JackWilb wants to merge 1 commit into
base: 3.0
Choose a base branch
from
Draft

Align Supabase docs with upstream self-hosting #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
34 changes: 26 additions & 8 deletions docs/data-and-deployment/supabase/enabling-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,47 @@
# Setting Up Authentication

:::warning
In order to use authentication, you must have a Supabase application already configured. To set up your Supabase application, please see [here](../setup).
Configure your Supabase deployment before enabling authentication; see [Configuring Supabase](./setup.md). Existing MinIO or pgsty installations must follow the [migration guide][supabase-migration] before using the new deployment configuration.
:::

## Enabling Authentication in Supabase

Supabase provides a variety of authentication methods.

:::info
Supabase supports multiple OAuth providers, but reVISit currently only officially supports GitHub OAuth. If you want to configure other providers in Supabase look at the [gotrue docs](https://github.com/netlify/gotrue).
Supabase supports multiple OAuth providers, but reVISit currently only officially supports GitHub OAuth. For other providers, see the [Supabase self-hosted authentication guide](https://supabase.com/docs/guides/self-hosting/auth).
:::

To enable GitHub OAuth, start by navigating to GitHub and creating a new OAuth application [here](http://github.com/settings/developers).
To enable GitHub OAuth, start by [creating a GitHub OAuth application](https://github.com/settings/developers).

Give your application a name, such as `ReVISit Supabase`. For the "Homepage URL", enter the URL where your reVISit application will be hosted (e.g., `https://my-revisit-app.com`). This must include the `https://` prefix.

Lastly set the "Authorization callback URL" to `https://<your-supabase-domain>/auth/v1/callback`, replacing `<your-supabase-domain>` with your actual Supabase domain (e.g., `https://supabase.organization.com/auth/v1/callback`).

![GitHub OAuth Setup](./img/github-oauth-setup.png)

After creating the OAuth application, you will be provided with a Client ID. Copy this in to the `supabase/.env` file in the `GITHUB_OAUTH_CLIENT_ID` field.
After creating the OAuth application, copy its Client ID and generate a Client Secret. Edit the `.env` in your **separate Supabase deployment directory**, not the reVISit application's `.env`:

Next, generate a new Client Secret by clicking the "Generate a new client secret" button. Copy this in to the `supabase/.env` file in the `GITHUB_OAUTH_CLIENT_SECRET` field.
```env title="Supabase deployment .env"
ENABLE_GITHUB_OAUTH=true
GITHUB_OAUTH_CLIENT_ID=<your-github-client-id>
GITHUB_OAUTH_SECRET=<your-github-client-secret>
GITHUB_OAUTH_REDIRECT_URI=https://<your-supabase-domain>/auth/v1/callback
API_EXTERNAL_URL=https://<your-supabase-domain>/auth/v1
SITE_URL=https://<your-revisit-domain>/<application-path>
```

Now, set the `GITHUB_OAUTH_REDIRECT_URI` field in the `supabase/.env` file to the same URL you used for the "Authorization callback URL" in GitHub.
Use the exact callback URL registered with GitHub. Set `SITE_URL` to your reVISit application's URL, including its path if applicable, and retain any required `ADDITIONAL_REDIRECT_URLS`. `API_EXTERNAL_URL` is the full Supabase Auth endpoint, including `/auth/v1`. During migration, preserve the registered callback and existing secrets as described in the migration guide.

Finally, ensure that your `SITE_URL` field in the `supabase/.env` file is set to the URL where your reVISit application will be hosted (e.g., `https://my-revisit-app.com/study`). If this is not set, the redirects won't work properly.
The upstream bundle needs reVISit's GitHub override to read these settings. From the Supabase deployment directory, copy the override from your matching reVISit checkout, enable it, and start the updated configuration:

```bash
cp /absolute/path/to/revisit-study/supabase/docker-compose.github.yml .
sh run.sh config add github
sh run.sh start
```

See the [complete self-hosted setup guide][supabase-setup] for deployment and key-generation instructions. Keep the client secret private and out of the application's public `VITE_*` variables.

## Enabling Authentication in reVISit

Expand All @@ -38,7 +53,7 @@ When you first enable authentication, you will be prompted to sign in using GitH

### Adding Additional Users

To add another administrator, simply navigate to the settings page (where you enabled authentication) and click on the "Add User" icon to the right of the "Enabled Users" section. Enter the Google account email for the user and click save. They will now be an administrator and will immediately be able to log into your reVISit application.
To add another administrator, simply navigate to the settings page (where you enabled authentication) and click on the "Add User" icon to the right of the "Enabled Users" section. Enter the email address associated with the user's GitHub account and click save. They will now be an administrator and will immediately be able to log into your reVISit application.

![Add User](./../img/manage_admin/add_user.png)

Expand All @@ -56,3 +71,6 @@ import StructuredLinks from '@site/src/components/StructuredLinks/StructuredLink
{name: "Supabase Authentication", url: "https://supabase.com/docs/guides/auth"},
]}
/>

[supabase-setup]: https://github.com/revisit-studies/study/blob/1669a47fa63860b39723b4e92a10f73dbbb8936c/supabase/README.md
[supabase-migration]: https://github.com/revisit-studies/study/blob/1669a47fa63860b39723b4e92a10f73dbbb8936c/supabase/MIGRATION.md
123 changes: 38 additions & 85 deletions docs/data-and-deployment/supabase/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,120 +1,68 @@
# Configuring Supabase

<a href="https://supabase.com/" target="_blank" >Supabase</a> is an open-source alternative to Firebase that provides a real-time database and storage solution. It is built on top of PostgreSQL, which allows for more complex queries and data structures. Supabase is particularly useful for researchers who need to comply with strict data privacy regulations, as it can be self-hosted.
[Supabase](https://supabase.com/) provides a PostgreSQL database, authentication, and file storage for reVISit. You can run it on a server you control or use a hosted Supabase project. This page covers self-hosting.

reVISit uses a pinned upstream Supabase deployment. The application repository's [`supabase/README.md`][supabase-setup] contains the supported release and complete setup commands. Supabase supplies the deployment configuration; reVISit's `supabase/` directory contains initialization, GitHub authentication, and migration support.

:::warning Existing installations
If you already run the previous bundled MinIO or pgsty stack, follow the [migration guide][supabase-migration] before starting the new configuration. Back up the database, object data, encryption volume, and configuration together. Storage applies one-way database migrations; changing image tags alone cannot undo them. The same guide contains the [exact rollback procedure][supabase-rollback].
:::

This guide will be focused on setting up a self-hosted Supabase instance for use with reVISit. If you would like to use a hosted solution, we suggest that you use the Firebase implementation instead. However, if you would like to use Supabase, as a hosted solution, you can follow the instructions on their website to stand up a hosted instance.
### Pre-requisites

Before you begin, ensure you have the following:
- A Linux server or cloud VM where you can install Supabase (EC2, DigitalOcean Droplet, etc.; Ubuntu LTS is recommended)
- Basic knowledge of Docker and Docker Compose
- SSH access to the remote server
- Access to your cloud firewall controls (EC2 Security Groups, DigitalOcean Cloud Firewall, or `ufw`)
- A domain name is strongly recommended if you plan to enable HTTPS/SSL
- A Linux server or cloud VM with SSH access and enough persistent disk space for Supabase and backups.
- Git, Docker Engine, Docker Compose v2 or newer, and OpenSSL. The setup guide also describes Node.js or Docker for key generation.
- A filesystem that supports Linux extended attributes for file storage.
- Access to your server's firewall settings and a domain name for HTTPS.

### Setting Up Supabase

Once your server or VM is running, follow these steps:

1. **SSH into the remote server**: From your local machine, connect to your server:
1. **Connect to your server** from your local machine:

```bash
ssh <user>@<server-ip>
```

All remaining setup commands in this section should be run on the remote server.

2. **Install Docker and Docker Compose**: If you don't have Docker installed, follow the [official Docker installation guide](https://docs.docker.com/get-docker/). Then install Docker Compose using the [Docker Compose installation guide](https://docs.docker.com/compose/install/).

3. **Clone the reVISit repository on the server**: Navigate to the directory where you want to host Supabase and clone the reVISit repository. If it already exists on the server, pull the latest changes.

4. **Navigate to the Supabase directory**: Inside the reVISit repository, navigate to the `supabase` directory.
Run deployment commands on the server.

5. **Update the `.env` file**: We provide a `.env` file that must be updated with your own credentials and secrets. Leaving defaults in place creates an insecure deployment. Follow the instructions on the [Supabase self-hosting documentation](https://supabase.com/docs/guides/self-hosting/docker#securing-your-services) to secure your `.env` file.
2. **Follow the [first-time setup guide][supabase-setup]** using the reVISit checkout matching this documentation. It walks you through obtaining the pinned upstream release, generating secrets, enabling anonymous participant sessions, and initializing the reVISit table and private storage bucket with `supabase/revisit.sql`.

6. **Start Supabase**: Run the following command to start Supabase using Docker Compose:
Keep the Supabase deployment in its own directory outside the application checkout. Its `.env` contains database credentials and deployment secrets. The `.env` at the root of the reVISit application is separate and contains the public connection settings below.

```bash
docker-compose up -d
```

This will pull the docker images and start the Supabase services in detached mode.

7. **Configure remote network access (important)**: For a remote server deployment, explicitly configure inbound firewall rules:
Run initialization only on a fresh database. Existing installations retain their schema and policies through the migration procedure. The supplied policies allow anyone holding the public application key to read and write reVISit records and objects; a private bucket does not provide participant-level isolation under these policies. Preserve any stricter policies you already use.

- **EC2 Security Group**: Allow `22` (SSH) from your admin IP; allow `80` and `443` from the internet if using a reverse proxy; only allow `8000` from trusted admin IPs if you must expose it directly.
- **DigitalOcean Cloud Firewall / `ufw`**: Same pattern as above. Keep dashboard/admin ports restricted whenever possible.
- Do **not** open database/internal ports publicly unless you have a specific, secured need.
3. **Configure network access**:

8. **Access the Supabase Dashboard**:
- Direct access (less secure): `http://<server-ip>:8000`
- Recommended while administering remotely: use an SSH tunnel from your local machine:
- Allow SSH only from trusted administration addresses.
- Expose the Supabase API through HTTPS on port `443`; see the reverse-proxy example below. Keep port `8000` private when using a reverse proxy.
- Keep database and pooler ports, including `5432` and `6543`, restricted.
- For remote dashboard administration, open an SSH tunnel from your local machine:

```bash
ssh -L 8000:localhost:8000 <user>@<server-ip>
```

Then open `http://localhost:8000` locally.

Log in using the credentials you set in the Supabase `.env` file.

:::info
For long-term deployments, prefer exposing Supabase through HTTPS on `443` via a reverse proxy and keep `8000` private.
:::

9. **Create a table for reVISit data**: You will need to create a table for storing user data. In the Supabase dashboard you should see that you're in the default project. From here click on "Table Editor" (the second icon) and then "New table" to create a new table. The table should be called `revisit` and should have the following columns

| Column Name | Data Type | Constraints |
|-------------|-----------|----------------------------|
| createdAt | Timestamp | Default: `now()` |
| studyId | Varchar | Primary Key |
| docId | Varchar | Primary Key |
| data | JSONB | Nullable |

**Notes:**
- Set both `studyId` and `docId` as composite primary keys.
- The `createdAt` column should automatically use the current timestamp.
- The `data` column can store any JSON object and can be left empty.

![Table Creation](./img/table-creation.png)

Save the table. The new table requires a policy to allow authenticated users to read and write to the table. You can do this by clicking on "Add RLS Policy" in the table editor and adding a new policy to the revisit table.

The policy should be called `allow_authenticated_read_write`, be on public.revisit, be Permissive, and allow all operations. Select "anon", "authenticated", and "service_role" as the roles that can access this policy. In the "using" block add `true`. At the bottom, uncheck "Use check expression". Now click "Save Policy".

![Table Policy](./img/table-policy.png)
Then open `http://localhost:8000` and log in with the deployment's generated dashboard credentials.

10. **Create a storage bucket**: In the Supabase dashboard, navigate to the "Storage" section (6th icon) and create a new bucket called `revisit`. This bucket will be used to store participant data, audio, configs, etc. Ensure that the bucket is not public, as we want to restrict access to the data to users of your reVISit deployment.
4. **Connect your reVISit application**. Set these variables in the application's root `.env`:

![Storage Bucket](./img/storage-bucket.png)

Since your bucket is not public, you will need to set up a policy to allow authenticated users to read and write to the bucket. You can do this by navigating to the "Policies" tab in the bucket settings and adding a new policy to the revisit bucket.

Name the policy `allow_authenticated_read_write` and allow select, insert, update, and delete operations. Select "anon", "authenticated", and "service_role" as the roles that can access this policy and click next. The top of the 4 policies should look like this:

```sql
CREATE POLICY "allow_authenticated_read_write i6w3co_0"
ON storage.objects
FOR SELECT TO anon, authenticated, service_role
USING (bucket_id = 'revisit');
```env title="reVISit application .env"
VITE_STORAGE_ENGINE="supabase"
VITE_SUPABASE_URL="https://<your-supabase-domain>"
VITE_SUPABASE_ANON_KEY="<SUPABASE_PUBLISHABLE_KEY from your deployment .env>"
```

Click save policy.
Use the Supabase base URL without `/auth/v1`. The application variable keeps its existing name and accepts the new publishable key. Migrated deployments can keep their existing `ANON_KEY`; follow the migration guide when preserving existing keys and sessions. Never put `SERVICE_ROLE_KEY` or `SUPABASE_SECRET_KEY` in the application configuration.

![Storage Policy](./img/storage-policy.png)
Restart the development server or rebuild and redeploy reVISit after changing these values. To enable Study Designer sign-in, follow [Setting Up Authentication](./enabling-authentication.md).

11. **Update your `.env` file in your deployed reVISit application**: In the root of your reVISit application, update the `.env` file with the following variables:
5. **Verify the deployment**. Complete a short study, confirm its participant data is stored, and check that it can be retrieved in a fresh browser. Restart Supabase and confirm the data persists and a new participant can submit answers. Check your configured Study Designer sign-in as well.

```env title=".env"
VITE_STORAGE_ENGINE="supabase"
VITE_SUPABASE_URL="https://<your-supabase-base-url>"
VITE_SUPABASE_ANON_KEY="<your-anon-key>"
```
Replace `<your-supabase-base-url>` with the public URL used by clients to reach Supabase (for example, `supabase.your-domain.com` or your server IP/port during testing), and `<your-anon-key>` with the anon key found in the Supabase `.env` file.
### Storage, backups, and updates

12. **Redeploy your reVISit application**: After updating the `.env` file, redeploy your reVISit application to ensure that it connects to the Supabase instance correctly.
The upstream default stores objects in `volumes/storage` and database files in `volumes/db/data`. The `db-config` named volume contains encryption material. Back these up together with writes paused, retain copies outside the server, and test restoration. Do not delete the volumes when stopping or recreating containers. File storage requires disk monitoring and does not provide replication or failover.

After following these steps, your reVISit application should be connected to your Supabase instance, and you can start collecting data from participants.
Follow [storage and ongoing operations][supabase-operations] for the supported update workflow and release caveats. Upgrades are explicit operations; updating the reVISit application does not update a separate Supabase deployment. Keep the [migration and rollback guide][supabase-migration] with your deployment records.

### HTTPS/SSL Configuration

Expand Down Expand Up @@ -157,3 +105,8 @@ import StructuredLinks from '@site/src/components/StructuredLinks/StructuredLink
{name: "Deploying to GitHub", url: "../../deploying-to-static-website"}
]}
/>

[supabase-setup]: https://github.com/revisit-studies/study/blob/1669a47fa63860b39723b4e92a10f73dbbb8936c/supabase/README.md
[supabase-migration]: https://github.com/revisit-studies/study/blob/1669a47fa63860b39723b4e92a10f73dbbb8936c/supabase/MIGRATION.md
[supabase-rollback]: https://github.com/revisit-studies/study/blob/1669a47fa63860b39723b4e92a10f73dbbb8936c/supabase/MIGRATION.md#rollback
[supabase-operations]: https://github.com/revisit-studies/study/blob/1669a47fa63860b39723b4e92a10f73dbbb8936c/supabase/README.md#storage-and-ongoing-operations
Loading