From 4a86bf1d92194b3307a9d1ded95e5aa861597f5c Mon Sep 17 00:00:00 2001
From: Marc-Antoine Parent <maparent@acm.org>
Date: Thu, 26 Jun 2025 09:28:22 -0400
Subject: [PATCH] ENG-520 dev instructions

---
 README.md                   | 16 ++++++++++++++++
 packages/database/README.md |  5 +++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 594ae2300..4b23bd4cf 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ Learn more about how monorepos improve development workflows [here](https://verc
 - [typescript-config](https://github.com/DiscourseGraphs/discourse-graph/tree/main/packages/typescript-config): Shared tsconfig.jsons
 - [eslint-config](https://github.com/DiscourseGraphs/discourse-graph/tree/main/packages/eslint-config): ESLint preset
 - [ui](https://github.com/DiscourseGraphs/discourse-graph/tree/main/packages/ui): Core React components
+- [database](https://github.com/DiscourseGraphs/discourse-graph/tree/main/packages/database): Database configuration
 
 ### Getting Started
 
@@ -59,6 +60,21 @@ You can use the `--filter` flag to run a single application, eg:
 turbo dev --filter roam
 ```
 
+4. Set up a supabase environment. This will cache and optimize some semantic queries. You may not need both environments, but you cannot develop unless `SUPABASE_URL` and `SUPABASE_ANON_KEY` are defined.
+   1. For local development:
+      1. Follow the local development setup steps [here](https://github.com/DiscourseGraphs/discourse-graph/tree/main/packages/database/README.md)
+      2. Start the local environment with `turbo dev`, and navigate to the (studio)[http://localhost:54323].
+      3. create a `.env.local` environment file, and set:
+         1. `SUPABASE_URL` from the `Project URL` in the (Data api tab)[http://localhost:54323/settings/api] of `Project Settings`
+         2. `SUPABASE_ANON_KEY` from the `anon`, `public` API key in the (API Keys tab)[http://localhost:54324/settings/api-keys] of `Project Settings.
+   2. To use your production database:
+      1. Create an account and project on [Supabase](https://supabase.com). (Free tiers available.) There you will get a <project_id>.
+      2. Navigate to your project studio. (URL should look like `https://supabase.com/dashboard/project/<project_id>`)
+      3. Set up a `.env.production` file
+         1. `SUPABASE_URL` from the `Project URL` in the `Data api` tab of `Project Settings`. URL should look like `https://supabase.com/dashboard/project/<project_id>/settings/api`
+         2. `SUPABASE_ANON_KEY` from the `anon`, `public` API key in the `API Keys` tab of `Project Settings`. URL should look like `https://supabase.com/dashboard/project/<project_id>/settings/api-keys`
+   3. To use a database branch on supabase (on the paid tier): Instructions (here)[https://supabase.com/docs/guides/deployment/branching]
+
 #### Roam
 
 - go to your graph, open up settings, and go to the extensions tab
diff --git a/packages/database/README.md b/packages/database/README.md
index 7a32ad33d..0d51b02b4 100644
--- a/packages/database/README.md
+++ b/packages/database/README.md
@@ -1,11 +1,12 @@
 This contains the database schema for vector embeddings and concepts.
 All CLI commands below should be run in this directory (`packages/database`.)
 
-1. Setup
+1. Local development setup
    1. Install [Docker](https://www.docker.com)
    2. Install the [supabase CLI](https://supabase.com/docs/guides/local-development). (There is a brew version)
    3. `supabase login` with your (account-specific) supabase access token. (TODO: Create a group access token.)
-   4. `supabase link`. It will ask you for a project name, use `discourse-graphs`. (Production for now.) It will also ask you for the database password (See 1password.)
+   4. If you have a supabase instance, connect to it with `supabase link`. It will ask you for its project name and password.
+      1. Team development: use `discourse-graphs`. (Production for now.) It will also ask you for the database password (See 1password.)
    5. Install [sqruff](https://github.com/quarylabs/sqruff)
 2. Usage:
    1. Use `turbo dev`, (alias for `supabase start`) before you use your local database. URLs will be given for your local supabase database, api endpoint, etc.