Installation

wanderer is composed of three key components:

A frontend built with SvelteKit
A backend, which is a custom fork of PocketBase
An index service, powered by Meilisearch

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

Prerequisites

wanderer 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. You can generate one using:

openssl rand -hex 16
# Example output: ce7f0ddb97100c42e6409a8537c11e23

Once you have set the encryption key, you can proceed to install wanderer.

Installation via Docker

This is the easiest and most convenient way to install wanderer.

After cloning the repository, you will find a docker-compose.yml file in the root directory. This file sets up all necessary components. Start everything by running:

docker compose up -d

Configuration Notes

If you’re not hosting wanderer at http://localhost:3000, update the ORIGIN environment variable accordingly:

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:

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

  web:
    container_name: wanderer-web
    image: flomp/wanderer-web
    depends_on:
      search:
        condition: service_healthy
      db:
        condition: service_started
    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
    ports:
      - "3000:3000"
    networks:
      - wanderer
    restart: unless-stopped

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.

Updating

To update your instance to the latest version:

docker compose pull
docker compose up -d

Always consult the changelog before updating, in case of breaking changes.

Installation from Source

While not as convenient as Docker, you can also install wanderer from source.

Prerequisites

Clone the repository:

git clone https://github.com/Flomp/wanderer.git --branch v{version} --single-branch

Install dependencies:
- Go ≥ 1.23.0
- Node.js ≥ 18.17.0
- npm ≥ 8.15.0

meilisearch

wanderer 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

wanderer uses a customized fork of PocketBase. You must build it before launching:

cd wanderer/db
go mod tidy && go build

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

Web

Build the frontend using:

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:

npm i -s vitest

Launch

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

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

Updating

To update to the latest version:

git pull origin main

Then re-run the launch script. Always review the changelog for breaking changes.

Verify the Installation

Regardless of the installation method, once everything is running you should be able to access wanderer at:

http://localhost:3000

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