Skip to main content
Prerequisites:
There are two ways to run the app locally:
  1. Supabase CLI (below). Best when you’re actively editing Edge Functions, since supabase functions serve watches your TypeScript and reloads on save.
  2. Docker Compose (jump to Self-hosting with Docker). Best for trying the full stack end-to-end without installing Node, Postgres, or the Supabase CLI on your host. Also what the Cypress E2E tests target.
Follow these steps to run Wanderer’s Guide locally on your system.
1

Clone our repository

And navigate to the created wanderers-guide directory.
2

Initialize Supabase locally

Make sure Docker is running and then run the following command:
This will print a few details about the Supabase local setup that will be required later.
3

Populate local database

Go into the data/ folder and run:
Replace <DB_URL> with the value obtained in step 2.This will create all the tables needed.
4

Set environment variables

In the frontend/ directory, copy .env.local.template to .env.local and replace the placeholder variables in .env.local:
  • Replace <API_URL> and <ANON_KEY> with the values obtained in step 2.
  • [Optional] If you’d like to roll virtual dice, <DDDICE_API_KEY> must be replaced with the API key to dddice
5

Install dependencies

Still in the frontend/ directory, run the following:
6

Serve the frontend

Use the following to run the frontend locally:
7

Serve the backend

In another terminal window, under the supabase/ directory, run the following:
8

Complete 🎉

Wanderer’s Guide should now be running locally! You can access it at: http://localhost:5173.To be able to log in, you need to have a user in the local database.

​
Creating a user

1

Visit Supabase studio

Go to the local supabase studio URL (default http://127.0.0.1:54323)
2

Create internal user record

On the authentication page, create a new user with email and password. Copy the user UID generated.
3

Create public user record

Go to the Table Editor page and select the public_user table.Create a new Public User record by clicking Insert -> Insert row.
  • Make sure to fill in the user_id field with the user UID generated in step 2.
4

Login to Wanderer's Guide

Back in the running Wanderer’s Guide, you can now log in with the email and password you had set.

​
Self-hosting with Docker

If you’d rather not install Node, Postgres, or the Supabase CLI on your host, the repo ships a docker-compose.yml that bundles the frontend with a self-hosted Supabase stack: Postgres, auth, REST, storage, edge functions, and the Kong gateway. Only Docker is required.
1

Configure environment

Edit .env to set JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY, and POSTGRES_PASSWORD.For local testing, the demo values from the Supabase docker example work as a matched set.
Do not use those demo values on a publicly reachable host. Generate fresh keys for any deployment.
2

Bring the stack up

3

Load schema and content data

This wipes and reloads the public schema, so it’s safe to re-run.
4

(Optional) Open Supabase Studio

Studio is handy for inspecting the DB while developing.
5

Open the app

Visit http://localhost:3000 and sign up with email + password.The DB ships with a trigger (installed by create-db-docker.sh) that auto-creates the matching public_user row, so the manual Studio insert from the Creating a user section is not needed for the docker stack.

​
Common docker operations

For the full wiring notes, what’s included, and what you’ll have to set up yourself (OAuth providers, SMTP, TLS termination, schema and content seed), see the Docker self-hosting guide.

​
Running end-to-end tests

Cypress runs against the Docker stack above. With npm run docker:start already running:
cy:e2e bakes in CYPRESS_BASE_URL=http://localhost:3000 and the default test creds ([email protected] / test1234). To scope to a single spec:
The same suite runs in CI on every PR via the e2e workflow. See .github/workflows/e2e.yml.

​
Running the API tests

Beyond the UI Cypress suite, the Edge Functions have their own Deno-based test harness:
The harness covers the auth-routing flow plus one representative test per pattern (find / create / update / delete / search), so a regression in the shared connect() wrapper or one of those patterns shows up immediately.

​
Troubleshooting

This is a common issue when Docker is not running or not properly installed. Make sure Docker is installed and running on your machine.In the case of a Mac or Windows machine, you can try restarting Docker Desktop.
This error indicates that the psql command-line tool for PostgreSQL is not installed or not in your system’s PATH. You can install it by following the instructions on the PostgreSQL website.If you have PostgreSQL installed but still see this error, ensure that the directory containing psql is included in your system’s PATH environment variable.
Curious about how to contribute? Check out our Discord server and GitHub issues!