Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wanderersguide.app/llms.txt

Use this file to discover all available pages before exploring further.

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

git clone https://github.com/wanderers-guide/wanderers-guide.git
And navigate to the created wanderers-guide directory.
2

Initialize Supabase locally

Make sure Docker is running and then run the following command:
supabase start
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:
./create-db.sh <DB_URL>
Replace <DB_URL> with the value obtained in step 2.
  • It should look something like: postgresql://postgres:postgres@127.0.0.1:54322/postgres
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:
npm i
6

Serve the frontend

Use the following to run the frontend locally:
npm run dev
7

Serve the backend

In another terminal window, under the supabase/ directory, run the following:
supabase functions serve
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

cp .env.docker.example .env
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

npm run docker:start
3

Load schema and content data

./data/create-db-docker.sh
This wipes and reloads the public schema, so it’s safe to re-run.
4

(Optional) Open Supabase Studio

docker compose --profile studio up -d
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

npm run docker:start    # bring the stack up
npm run docker:stop     # stop containers (keeps the db volume)
npm run docker:rebuild  # rebuild + recreate the frontend container after source changes
                        # (Vite envs are baked in at build time)
npm run docker:reset    # wipe and reseed: down -v, up --wait, schema/data, cypress test user

docker compose ps                 # status
docker compose logs -f frontend   # tail one service's logs
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: 
./data/seed-test-user.sh                  # one-time per fresh DB
npm --prefix frontend run cy:e2e          # headless run of all specs
npm --prefix frontend run cy:e2e:open     # interactive Cypress UI
cy:e2e bakes in CYPRESS_BASE_URL=http://localhost:3000 and the default test creds (test@wanderersguide.app / test1234). To scope to a single spec: 
npm --prefix frontend run cy:e2e -- --spec "cypress/e2e/login/*.cy.ts"
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: 
npm run docker:start                      # supabase stack must be up
npm run test:api                          # cd supabase && deno test --allow-net --allow-env --allow-read functions/_tests/
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!