chore: local dev setup by leandrocp · Pull Request #1823 · supabase/realtime

leandrocp · 2026-04-20T17:10:15Z

Improve the local setup to make it straightforward to run the server:

mise run db-start
mix setup
mise run dev

Introduce mise to manage tool versions, tasks, and envs
Removed .tool-versions and Makefile in favor of mise.toml
Introduce Realtime.Env to use in runtime.exs with tests and more validations to make it more resilient to avoid hard to debug errors in the server booting process
Group all envs together in runtime.exs to have better discoverability, especially for docs (self-hosting) and config
Break readme into dedicated docs to reduce noise in the main readme (easier to scan)
Add Code of Conduct and Contributing guides based on https://github.com/supabase/.github and https://github.com/supabase/supabase
Added env vars into ENVS.md: API_TOKEN_BLOCKLIST, CLUSTER_STRATEGIES, DB_MASTER_REGION, DB_HOST_REPLICA_FRA, DB_HOST_REPLICA_IAD, DB_HOST_REPLICA_SIN, DB_HOST_REPLICA_SJC, REGION, LOGS_ENGINE, LOGFLARE_LOGGER_BACKEND_URL, LOGFLARE_API_KEY, LOGFLARE_SOURCE_ID, JWT_CLAIM_VALIDATORS, METRICS_JWT_SECRET, METRICS_TOKEN_BLOCKLIST, MAX_GEN_RPC_CALL_CLIENTS, PROM_POLL_RATE, AWS_EXECUTION_ENV, JANITOR_MAX_CHILDREN, JANITOR_CHILDREN_TIMEOUT, LOG_THROTTLE_JANITOR_INTERVAL_IN_MS, MEASURE_TRAFFIC_INTERVAL_IN_MS, NO_CHANNEL_TIMEOUT_IN_MS, RPC_TIMEOUT
Removed stale env vars from ENVS.md: DISCONNECT_SOCKET_ON_NO_CHANNELS_INTERVAL_IN_MS, JANITOR_CLEANUP_MAX_CHILDREN, JANITOR_CLEANUP_CHILDREN_TIMEOUT

Improve the local setup to make it straightforward to run the server: ``` mise run db-start mix setup mise run dev ``` - Introduce mise to manage tool versions, tasks, and envs - Removed .tool-versions and Makefile in favor of mise.toml - Introduce `Realtime.Env` to use in runtime.exs with tests and more validations to make it more resilient to avoid hard to debug errors in the server booting process - Group all envs together in `runtime.exs` to have better discoverability, especially for docs (self-hosting) and config - Break readme into dedicated docs to reduce noise in the main readme (easier to scan) - Add Code of Conduct and Contributing guides based on https://github.com/supabase/.github and https://github.com/supabase/supabase - Added env vars into ENVS.md: API_TOKEN_BLOCKLIST, CLUSTER_STRATEGIES, DB_MASTER_REGION, DB_HOST_REPLICA_FRA, DB_HOST_REPLICA_IAD, DB_HOST_REPLICA_SIN, DB_HOST_REPLICA_SJC, REGION, LOGS_ENGINE, LOGFLARE_LOGGER_BACKEND_URL, LOGFLARE_API_KEY, LOGFLARE_SOURCE_ID, JWT_CLAIM_VALIDATORS, METRICS_JWT_SECRET, METRICS_TOKEN_BLOCKLIST, MAX_GEN_RPC_CALL_CLIENTS, PROM_POLL_RATE, AWS_EXECUTION_ENV, JANITOR_MAX_CHILDREN, JANITOR_CHILDREN_TIMEOUT, LOG_THROTTLE_JANITOR_INTERVAL_IN_MS, MEASURE_TRAFFIC_INTERVAL_IN_MS, NO_CHANNEL_TIMEOUT_IN_MS, RPC_TIMEOUT - Removed stale env vars from ENVS.md: DISCONNECT_SOCKET_ON_NO_CHANNELS_INTERVAL_IN_MS, JANITOR_CLEANUP_MAX_CHILDREN, JANITOR_CLEANUP_CHILDREN_TIMEOUT wip

leandrocp · 2026-04-20T17:11:10Z

-seed: ## Seed the database
-	DB_ENC_KEY="1234567890123456" FLY_ALLOC_ID=123e4567-e89b-12d3-a456-426614174000 mix run priv/repo/dev_seeds.exs
-
-prod: ## Start a server with a MIX_ENV=prod


I'm assuming this is (was?) used to run a prod-like env but it seems outdated. I did not migrate to mise.toml because I'm not sure if it's still needed.

leandrocp · 2026-04-20T17:12:44Z

+    <a href="https://supabase.com/docs/guides/realtime#examples">Examples</a>
    ·
-    <a href="https://github.com/supabase/realtime/issues/new?assignees=&labels=enhancement&template=2.Feature_request.md">Request Feature</a>
+    <a href="https://github.com/orgs/supabase/discussions/new?category=feature-requests">Request Features</a>


Linking to https://github.com/orgs/supabase/discussions/new?category=feature-requests instead of a local PR becase 1) we don't have a Feature Request template and 2) it seems to be the place where requests are currently made but I'm not sure.

leandrocp · 2026-04-20T17:15:48Z

A lot of changes here but mostly:

renaming vars to match the env name, for eg pool_size-> db_pool_size named after DB_POOL_SIZE which I find easier to maintain and also more explicit (same is true for other envs).

moving all env loading together to make it easier to scan and maintain

Another big change is introducing Realtime.Env, I can revert it if that's not the pattern we're looking for but I added it to avoid those usual hard to debug issues with env vars when booting the server, for eg with the previous code typos could cause unexpected behavior:

System.put_env("SERVICE_A_ENABLED", "falsee") Env.get_boolean("SERVICE_A_ENABLED", false) #=> :falsee if Env.get_boolean("SERVICE_A_ENABLED", false) do "Service A ENABLED" else "Service A DISABLED" end #=> "Service A ENABLED""

Among other potential issues so I think it's worth the having that modules and also having tests.

I tried to make less changes as possible given the criticality of this file so please 👀

leandrocp · 2026-04-20T17:21:06Z

Nothing changed, just copied from README

leandrocp · 2026-04-20T17:21:15Z

Nothing changed, just copied from README

coveralls · 2026-04-20T17:29:32Z

Coverage is 91.948% — fix/repo-setup into main. No base build found for main.

leandrocp · 2026-04-20T17:42:40Z

          docker image save ${{ env.POSTGRES_IMAGE }} | zstd -T0 -o /tmp/docker-images/postgres.tar.zst
          docker image save ${{ env.DENO_IMAGE }} | zstd -T0 -o /tmp/docker-images/deno.tar.zst
      - name: Run integration test
-        run: docker compose -f docker-compose.tests.yml up --abort-on-container-exit --exit-code-from test-runner


compose{-*}.yml is shorter and more popular nowadays :)

leandrocp · 2026-04-20T18:02:46Z

Hey @aantti I'm onboarding and noticed some potential fixes and improvements during the initial local setup and would be interesting to have your feedback since it's touching the contributing guides and I believe we need to update https://supabase.com/docs/guides/self-hosting/realtime/config as well.

In short the main changes that impact contributors and potentially external projects:

Adopting mise
Renaming compose files
Introducing CONTRIBUTING.md, DEVELOPERS.md and COC

filipecabaco · 2026-04-21T14:03:42Z

+- Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) when you can.
+- Tests are passing.
+- You have reviwed the code.
+


should we reference that we should have fix: or feat: ?

Yep good idea, I've improved the PR section to recommend good practices but not enforce because at the end of the day it's our responsibility to squash good commit messages into main. Also included some examples of good/bad commit messages using fix: and feat:

…-setup

one last pass before merging

leandrocp commented Apr 20, 2026

View reviewed changes

Comment thread OBSERVABILITY_METRICS.md

Copy link
Copy Markdown

Contributor Author

leandrocp Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing changed, just copied from README

leandrocp commented Apr 20, 2026

View reviewed changes

Comment thread ERROR_CODES.md

Copy link
Copy Markdown

Contributor Author

leandrocp Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing changed, just copied from README

leandrocp force-pushed the fix/repo-setup branch from 0dd44ba to 1c0da7b Compare April 20, 2026 17:28

fix tests

bf88cc6

leandrocp force-pushed the fix/repo-setup branch from 1c0da7b to bf88cc6 Compare April 20, 2026 17:30

leandrocp commented Apr 20, 2026

View reviewed changes

filipecabaco reviewed Apr 21, 2026

View reviewed changes

filipecabaco approved these changes Apr 21, 2026

View reviewed changes

leandrocp added 6 commits April 21, 2026 11:17

fix CONTRIBUTING PR section

7c84e83

add examples

b0dfe53

Merge main into fix/repo-setup

a5f527e

Merge commit 'b0dfe5317289e3d08019cd819d380a02c96c0d74' into fix/repo…

b449912

…-setup

fixes

ac56cf8

one last pass before merging

fix required METRICS_JWT_SECRET

fafe245

leandrocp changed the title ~~feat: local dev setup~~ chore: local dev setup Apr 21, 2026

leandrocp merged commit 476f16b into main Apr 21, 2026
8 checks passed

leandrocp deleted the fix/repo-setup branch April 21, 2026 16:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: local dev setup#1823

chore: local dev setup#1823
leandrocp merged 8 commits intomainfrom
fix/repo-setup

leandrocp commented Apr 20, 2026

Uh oh!

leandrocp Apr 20, 2026

Uh oh!

leandrocp Apr 20, 2026

Uh oh!

leandrocp Apr 20, 2026 •

edited

Loading

Uh oh!

leandrocp Apr 20, 2026

Uh oh!

leandrocp Apr 20, 2026

Uh oh!

coveralls commented Apr 20, 2026 •

edited

Loading

Uh oh!

leandrocp Apr 20, 2026

Uh oh!

leandrocp commented Apr 20, 2026

Uh oh!

filipecabaco Apr 21, 2026

Uh oh!

leandrocp Apr 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

leandrocp commented Apr 20, 2026

Uh oh!

leandrocp Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

leandrocp Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

leandrocp Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leandrocp Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

leandrocp Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

coveralls commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

leandrocp Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

leandrocp commented Apr 20, 2026

Uh oh!

filipecabaco Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

leandrocp Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

leandrocp Apr 20, 2026 •

edited

Loading

coveralls commented Apr 20, 2026 •

edited

Loading