---
title: Installation
description: Detailed installation instructions for Docker and bare-metal
---
import { version } from '../../../../package.json';

<span class="-tracking-[0.075em]">wanderer</span> is composed of three key components:

1. A frontend built with [SvelteKit](https://github.com/sveltejs/kit)  
2. A backend, which is a custom fork of [PocketBase](https://github.com/pocketbase/pocketbase)  
3. An index service, powered by [Meilisearch](https://github.com/meilisearch/meilisearch)

You can install these components either via Docker (recommended) or from source.

---

## Prerequisites

<span class="-tracking-[0.075em]">wanderer</span> uses encrypted secrets such as passwords and private keys. To support this, you must set an encryption key using the `POCKETBASE_ENCRYPTION_KEY` [environment variable](/run/environment-configuration#pocketbase). You can generate one using:

```bash
openssl rand -hex 16
# Example output: ce7f0ddb97100c42e6409a8537c11e23
```

:::caution
Do not share this key with anyone!
:::

Once you have set the encryption key, you can proceed to install <span class="-tracking-[0.075em]">wanderer</span>.

## Installation via Docker

This is the easiest and most convenient way to install <span class="-tracking-[0.075em]">wanderer</span>.

After cloning the repository, you will find a [`docker-compose.yml`](https://github.com/Flomp/wanderer/blob/main/docker-compose.yml) file in the root directory. This file sets up all necessary components. Start everything by running:

```bash
docker compose up -d
```

### Configuration Notes

If you're not hosting <span class="-tracking-[0.075em]">wanderer</span> at `http://localhost:3000`, update the `ORIGIN` environment variable accordingly:

```env
ORIGIN=http(s)://<your_domain>:<your_port>
```

If this is not set correctly, you may encounter CORS-related issues.

### Docker Compose Overview

Here's a minimal `docker-compose.yml` example with explanations:

```yaml
version: '3'

x-common-env: &cenv
  MEILI_URL: http://search:7700
  MEILI_MASTER_KEY: vODkljPcfFANYNepCHyDyGjzAMPcdHnrb6X5KyXQPWo

services:
  search:
    container_name: wanderer-search
    image: getmeili/meilisearch:v1.11.3
    environment:
      <<: *cenv
      MEILI_NO_ANALYTICS: "true"
    ports:
      - 7700:7700
    networks:
      - wanderer
    volumes:
      - ./data/data.ms:/meili_data/data.ms
    restart: unless-stopped
    healthcheck:
      test: curl --fail http://localhost:7700/health || exit 1
      interval: 15s
      retries: 10
      start_period: 20s
      timeout: 10s

  db:
    container_name: wanderer-db
    image: flomp/wanderer-db
    depends_on:
      search:
        condition: service_healthy
    environment:
      <<: *cenv
      POCKETBASE_ENCRYPTION_KEY: <YOUR_ENCRYPTION_KEY_HERE>
      ORIGIN: http://localhost:3000
    ports:
      - "8090:8090"
    networks:
      - wanderer
    restart: unless-stopped
    volumes:
      - ./data/pb_data:/pb_data
    healthcheck:
      test: wget --spider -q http://localhost:8090/health || exit 1
      interval: 15s
      retries: 10
      start_period: 20s
      timeout: 10s

  web:
    container_name: wanderer-web
    image: flomp/wanderer-web
    depends_on:
      search:
        condition: service_healthy
      db:
        condition: service_healthy
    environment:
      <<: *cenv
      ORIGIN: http://localhost:3000
      BODY_SIZE_LIMIT: Infinity
      PUBLIC_POCKETBASE_URL: http://db:8090
      PUBLIC_DISABLE_SIGNUP: "false"
      UPLOAD_FOLDER: /app/uploads
      UPLOAD_USER:
      UPLOAD_PASSWORD:
      PUBLIC_VALHALLA_URL: https://valhalla1.openstreetmap.de
      PUBLIC_NOMINATIM_URL: https://nominatim.openstreetmap.org
    volumes:
      - ./data/uploads:/app/uploads
      # - ./data/about.md:/app/build/client/md/about.md
    ports:
      - "3000:3000"
    networks:
      - wanderer
    restart: unless-stopped
    healthcheck:
      test: curl --fail http://localhost:3000/ || exit 1
      interval: 15s
      retries: 10
      start_period: 20s
      timeout: 10s

networks:
  wanderer:
    driver: bridge
```

### Networking

All services must be part of the same Docker network. This is handled by the default `wanderer` network in the configuration above.

Make sure to set the `ORIGIN` environment variable to the full public URL (including port) where your instance is reachable. If misconfigured, the frontend will show this error:

> Cross-site POST form submissions are forbidden

### Volumes

By default, two volumes are mounted:

- Meilisearch index data: `./data/data.ms`
- PocketBase data: `./data/pb_data`

These can be changed to bind mounts or other volume strategies if needed.

### Environment

The default Docker configuration defines all necessary environment variables. You can extend or override them as needed. For advanced options, refer to the [environment configuration documentation](/run/environment-configuration).

:::caution
Ensure you replace the default `MEILI_MASTER_KEY` with a strong, unique value in production environments. Also, remember to set the `POCKETBASE_ENCRYPTION_KEY` to the key you generated [before](#prerequisites).
:::

### Updating

To update your instance to the latest version:

```bash
docker compose pull
docker compose up -d
```

Always consult the [changelog](/changelog) before updating, in case of breaking changes.

## Installation from Source

While not as convenient as Docker, you can also install <span class="-tracking-[0.075em]">wanderer</span> from source.

### Prerequisites

1. Clone the repository:

```bash
git clone https://github.com/Flomp/wanderer.git --branch v{version} --single-branch
```
2. Install dependencies:
   - **Go** ≥ 1.23.0
   - **Node.js** ≥ 18.17.0
   - **npm** ≥ 8.15.0

### meilisearch

<span class="-tracking-[0.075em]">wanderer</span> uses a standard Meilisearch binary. Download and install it according to your platform:

https://www.meilisearch.com/docs/learn/getting_started/installation

Place the binary in `wanderer/search`. If you choose a different location, update your scripts accordingly.

### PocketBase

<span class="-tracking-[0.075em]">wanderer</span> uses a customized fork of PocketBase. You must build it before launching:

```bash
cd wanderer/db
go mod tidy && go build
```

This will generate a `pocketbase` binary in the `wanderer/db` folder.

### Web

Build the frontend using:

```bash
cd wanderer/web
npm ci --omit=dev
npm run build
```

You should see a `build/` directory in `wanderer/web`.

If `vitest` is not installed, add it manually:

```bash
npm i -s vitest
```

### Launch

You can launch all three services using a shell script that sets environment variables and ensures proper startup order:

```bash
trap "kill 0" EXIT

# Required configuration
export ORIGIN=http://localhost:3000
export MEILI_URL=http://127.0.0.1:7700
export MEILI_MASTER_KEY=YOU_SHOULD_DEFINITELY_CHANGE_ME
export PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090
export PUBLIC_VALHALLA_URL=https://valhalla1.openstreetmap.de
export POCKETBASE_ENCRYPTION_KEY=YOUR_ENCRYPTION_KEY_HERE

# Optional configuration
# export MEILI_NO_ANALYTICS=true
# export BODY_SIZE_LIMIT=Infinity
# export PUBLIC_DISABLE_SIGNUP=false
# export UPLOAD_FOLDER=/app/uploads
# export UPLOAD_USER=
# export UPLOAD_PASSWORD=

cd search && ./meilisearch --master-key $MEILI_MASTER_KEY &
cd db && ./pocketbase serve &
cd web && node build &

wait
```

:::caution
Make sure you replace `MEILI_MASTER_KEY` with a secure value before going to production. Also, remember to set the `POCKETBASE_ENCRYPTION_KEY` to the key you generated [before](#prerequisites).
:::

### Updating

To update to the latest version stop the running application and run:

```bash
git pull origin main

cd wanderer/db
go mod tidy && go build

cd wanderer/web
npm ci --omit=dev
npm run build
```

Then re-run the launch script. Always review the [changelog](/changelog) for breaking changes.

## Verify the Installation

Regardless of the installation method, once everything is running you should be able to access <span class="-tracking-[0.075em]">wanderer</span> at:

```
http://localhost:3000
```

If you see the UI and no errors in the logs, you're all set!
