Skip to content

Installation

Flomp edited this page May 23, 2024 · 16 revisions

Installation

wanderer consists of three components:

  1. the frontend written with SvelteKit
  2. the backend, a custom PocketBase fork
  3. 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. Please note that due to the bootstrapping task the first start will take a little bit.

version: '3'

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

services:
  search:
    container_name: wanderer-search
    image: flomp/wanderer-search
    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
    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.

Caution: Ensure that you change the MEILI_MASTER_KEY to a different value if you plan to use wanderer in a production environment.

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

  1. git installed && git clone https://github.com/Flomp/wanderer.git
  2. go >= 1.21.1 installed
  3. node >= 18.17.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.

Furthermore, you will need to import the cities index manually. To do so launch meilisearch once with --import-dump parameter:

./meilisearch --import-dump wanderer/search/migrations/migration.dump

Wait for the process to finish and terminate meilisearch afterwards.

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.

Caution: Ensure that you change the MEILI_MASTER_KEY to a different value if you plan to use wanderer in a production environment.

trap "kill 0" EXIT

export ORIGIN=http://localhost:5173
export MEILI_URL=http://127.0.0.1:7700
export MEILI_MASTER_KEY=CHANGE_ME!
export PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090
export PUBLIC_VALHALLA_URL=https://valhalla1.openstreetmap.de

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

wait

Verify the installation

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

Bootstrapping

On the first launch, wanderer will create a rather large city index with over 200,000 entries in meilisearch. This process happens automatically but can take up to 2 minutes to complete. During this time the search functionality might not yet work properly.

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.