Installation

wanderer consists of three components:

the frontend written with SvelteKit
the backend, a custom PocketBase fork
the index, a standard meilisearch application

You can install these components in two ways.

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 that will install and run all necessary components by running docker compose up -d.

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
    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 three components must be on the same network for wanderer to function properly. This is the case in the default configuration shown above. However, if you run wanderer behind a proxy like traefik, please ensure all three components can communicate. Notice that you must set the ORIGIN environment variable for the web service to the public IP or hostname including the port that wanderer is reachable at. Otherwise, you will see wanderer’s frontend throw an Cross-site POST form submissions are forbidden error.

The standard configuration makes all three services publically available by forwarding their ports. For the database and the index service this is not strictly necessary. In case you do not require direct access to them you can disable their ports in the docker-compose file.

Volumes

By default, wanderer uses two volumes. One for meilisearch indices and one for all PocketBase data. In the default configuration, the data is stored in volumes. However, if you prefer to use bind mounts you can simply adapt the configuration accordingly.

Environment

The default configuration contains all necessary environment variables. However, there are more options that allow you to modify how the backend and index operate. For more details, you can take a look at the respective section of the documentation.

Updating

To update all containers to a new version simply run docker compose pull && docker compose up -d. Make sure to read the changelog to check for breaking changes.

From source

While not recommended it is absolutely possible to install wanderer from source.

Prerequisites

git installed && git clone https://github.com/Flomp/wanderer.git —branch v0.15.2 —single-branch
go >= 1.21.1 installed
node >= 18.17.0 installed
npm >= 8.15.0 installed

meilisearch

wanderer uses meilisearch without any further modifications. As a result, you can simply head over to their website and follow the instructions for your preferred platform. We assume that you put the binary in the wanderer/search directory. If you did not, adapt the launch script below accordingly.

PocketBase

wanderer uses a slightly modified version of the PocketBase backend framework. As a result, you will need to build the PocketBase binary first.

cd wanderer/db
go mod tidy && go build

This will create a binary in the wanderer/db folder. Verify that it is there.

Web

wanderer’s frontend is written in SvelteKit. We first install all dependencies and build the project.

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

This will create a directory wanderer/web/build. Verify that it is there.

Launch

To launch our three services we will use a small bash script. This ensures that all necessary environment variables are set and the services are started in the correct order. All three services are executed as background tasks, but are being trapped so that terminating the bash script will also terminate all three services at once.

trap "kill 0" EXIT

# learn more about the configuration:
# https://wanderer.to/getting-started/configuration/
# required
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

# optional
# 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 wanderer to the newest version simply run git pull origin main and run the launch script. Make sure to read the changelog to check for breaking changes.

Verify the installation

No matter which installation method you chose, you should now be able to access wanderer on localhost:3000.