> ## 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.

# Development

> Running Wanderer's Guide locally

<Info>
  **Prerequisites**:

  * [Node.js](https://nodejs.org/en/download) version 19 or higher
  * [Docker](https://www.docker.com/)
  * [Supabase CLI](https://supabase.com/docs/guides/local-development) for your OS (follow the instructions [here](https://supabase.com/docs/guides/cli/getting-started))
  * [Postgres](https://www.postgresql.org/), need `psql` (the client command line)
</Info>

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](#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](#running-end-to-end-tests) target.

Follow these steps to run Wanderer's Guide locally on your system.

<Steps>
  <Step title="Clone our repository">
    ```bash theme={null}
    git clone https://github.com/wanderers-guide/wanderers-guide.git
    ```

    And navigate to the created `wanderers-guide` directory.
  </Step>

  <Step title="Initialize Supabase locally">
    Make sure Docker is running and then run the following command:

    ```bash theme={null}
    supabase start
    ```

    This will print a few details about the Supabase local setup that will be required later.
  </Step>

  <Step title="Populate local database">
    Go into the `data/` folder and run:

    ```bash theme={null}
    ./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.
  </Step>

  <Step title="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](https://dddice.com)
      * The API key can be generated by creating a [dddice](https://dddice.com) account, visiting ["My Account" -> "Developers"](https://dddice.com/account/developer) and clicking on "Create API Key"
  </Step>

  <Step title="Install dependencies">
    Still in the `frontend/` directory, run the following:

    ```bash theme={null}
    npm i
    ```
  </Step>

  <Step title="Serve the frontend">
    Use the following to run the frontend locally:

    ```bash theme={null}
    npm run dev
    ```
  </Step>

  <Step title="Serve the backend">
    In another terminal window, under the `supabase/` directory, run the following:

    ```bash theme={null}
    supabase functions serve
    ```
  </Step>

  <Step title="Complete 🎉">
    Wanderer's Guide should now be running locally! You can access it at: [http://localhost:5173](http://localhost:5173).

    To be able to log in, you need to have a user in the local database.
  </Step>
</Steps>

## Creating a user

<Steps>
  <Step title="Visit Supabase studio">
    Go to the local supabase studio URL (default [http://127.0.0.1:54323](http://127.0.0.1:54323))
  </Step>

  <Step title="Create internal user record">
    On the authentication page, create a new user with email and password.
    Copy the user UID generated.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Steps>
  <Step title="Configure environment">
    ```bash theme={null}
    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](https://github.com/supabase/supabase/blob/master/docker/.env.example) work as a matched set.

    <Warning>Do not use those demo values on a publicly reachable host. Generate fresh keys for any deployment.</Warning>
  </Step>

  <Step title="Bring the stack up">
    ```bash theme={null}
    npm run docker:start
    ```
  </Step>

  <Step title="Load schema and content data">
    ```bash theme={null}
    ./data/create-db-docker.sh
    ```

    This wipes and reloads the public schema, so it's safe to re-run.
  </Step>

  <Step title="(Optional) Open Supabase Studio">
    ```bash theme={null}
    docker compose --profile studio up -d
    ```

    Studio is handy for inspecting the DB while developing.
  </Step>

  <Step title="Open the app">
    Visit [http://localhost:3000](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](#creating-a-user) section is **not needed for the docker stack**.
  </Step>
</Steps>

### Common docker operations

```bash theme={null}
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](/docker).

## Running end-to-end tests

Cypress runs against the Docker stack above. With `npm run docker:start` already running:

```bash theme={null}
./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:

```bash theme={null}
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`](https://github.com/wanderers-guide/wanderers-guide/blob/main/.github/workflows/e2e.yml).

## Running the API tests

Beyond the UI Cypress suite, the Edge Functions have their own [Deno-based test harness](https://github.com/wanderers-guide/wanderers-guide/tree/main/supabase/functions/_tests):

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Error: Cannot connect to the Docker daemon">
    This is a common issue when Docker is not running or not properly installed. Make sure [Docker](https://www.docker.com/products/docker-desktop/) is installed and running on your machine.

    In the case of a Mac or Windows machine, you can try restarting Docker Desktop.
  </Accordion>

  <Accordion title="Error: psql command not found">
    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](https://www.postgresql.org/download/).

    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.
  </Accordion>
</AccordionGroup>

<Note>
  Curious about how to contribute? Check out our [Discord server](https://discord.com/invite/FxsFZVvedr) and [GitHub issues](https://github.com/wanderers-guide/wanderers-guide/issues)!
</Note>