From bd0d0168d63b93b47c85b10da836fa80de0008ee Mon Sep 17 00:00:00 2001 From: Jack Wilburn Date: Sun, 18 Oct 2026 19:19:46 -0600 Subject: [PATCH] Align Supabase docs with pinned upstream deployment --- .../supabase/enabling-authentication.md | 34 +++-- docs/data-and-deployment/supabase/setup.md | 123 ++++++------------ 2 files changed, 64 insertions(+), 93 deletions(-) diff --git a/docs/data-and-deployment/supabase/enabling-authentication.md b/docs/data-and-deployment/supabase/enabling-authentication.md index 018849a119b..0a573f53cd7 100644 --- a/docs/data-and-deployment/supabase/enabling-authentication.md +++ b/docs/data-and-deployment/supabase/enabling-authentication.md @@ -1,7 +1,7 @@ # 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 @@ -9,10 +9,10 @@ In order to use authentication, you must have a Supabase application already con 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. @@ -20,13 +20,28 @@ Lastly set the "Authorization callback URL" to `https:///a ![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= +GITHUB_OAUTH_SECRET= +GITHUB_OAUTH_REDIRECT_URI=https:///auth/v1/callback +API_EXTERNAL_URL=https:///auth/v1 +SITE_URL=https:/// +``` -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 @@ -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) @@ -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 diff --git a/docs/data-and-deployment/supabase/setup.md b/docs/data-and-deployment/supabase/setup.md index 53c1caeab5e..60c4ebbf038 100644 --- a/docs/data-and-deployment/supabase/setup.md +++ b/docs/data-and-deployment/supabase/setup.md @@ -1,120 +1,68 @@ # Configuring Supabase -Supabase 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 @ ``` - 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://: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 @ ``` - 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://" + VITE_SUPABASE_ANON_KEY="" ``` - 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://" - VITE_SUPABASE_ANON_KEY="" - ``` - Replace `` with the public URL used by clients to reach Supabase (for example, `supabase.your-domain.com` or your server IP/port during testing), and `` 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 @@ -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