wanderer: a self-hosted trail catalogue built on PocketBase and Meilisearch

What wanderer solves, and who ends up running it

A folder of GPX files is a poor catalogue. You can list it, but you cannot ask which of last year's rides started within 20 kilometres of a given town, or which hikes share a segment, without opening each file. wanderer is built for that gap. The README describes it as "a self-hosted trail database" where you "upload your recorded tracks or create new ones and add various metadata to build an easily searchable catalogue".

The audience is narrow on purpose. You need somewhere to run three containers, a domain or a local address, and a willingness to keep a search index alive next to a database. In exchange you get no account limits, no per-track pricing, and no third party holding the coordinates of where you walk. The feature list in the README is short and concrete: manage trails, plan new routes, map integration, sharing, filters, and custom lists. Nothing in it suggests a social network or a training analytics platform, and that restraint is the point.

Three containers, two datastores, one search index

The docker-compose.yml at the repository root defines three services. search runs getmeili/meilisearch:v1.36.0 and exposes port 7700. db runs flomp/wanderer-db and exposes 8090. web runs flomp/wanderer-web and is the piece you actually open in a browser.

The dependency order is explicit. Both db and web declare depends_on with condition: service_healthy against search, so the Meilisearch healthcheck on /health has to pass before either starts. That ordering tells you something about the architecture: the PocketBase layer is not self-sufficient. Trails are stored in PocketBase, but queries go through Meilisearch, so a dead search container is not a degraded experience, it is a failed startup.

State lives in two bind mounts. Meilisearch writes to ./data/data.ms, and PocketBase writes to ./data/pb_data. A third mount, ./data/plugins, receives the plugin binaries that the Makefile copies in with plugins-install-local. The plugins directory in the repository holds a Go SDK plus hammerhead, komoot and strava integrations, so the intended path for pulling tracks from those services is a plugin rather than a built-in importer. The README does not document what happens to existing trails if the Meilisearch volume is lost while pb_data survives, which is the failure mode worth thinking about before you rely on this.

Installing wanderer with Docker Compose and uploading a first track

The README calls Docker Compose the recommended and quickest route. It gives two commands: fetch the compose file, then bring the stack up detached. The first startup can take up to 90 seconds, after which the frontend answers on localhost:3000.

wget https://raw.githubusercontent.com/open-wanderer/wanderer/main/docker-compose.yml

docker compose up -d

Two environment variables matter before you expose this to anyone. ORIGIN must match the address you actually serve from, or you get CORS errors, and the README states this directly. MEILI_MASTER_KEY must be changed in a production environment; the value shipped in the compose file is a working default, not a secret. The same file also carries POCKETBASE_ENCRYPTION_KEY and POCKETBASE_PROXY_SECRET, both of which are defaulted and both of which sit in the same file you just downloaded.

environment:
  MEILI_URL: http://search:7700
  MEILI_MASTER_KEY: vODkljPcfFANYNepCHyDyGjzAMPcdHnrb6X5KyXQPWo
  ORIGIN: http://localhost:3000
  POCKETBASE_ENCRYPTION_KEY: fde406459dc1f6ca6f348e1f44a9a2af
  POCKETBASE_PROXY_SECRET: dev-proxy-secret-change-me

Once the web container is healthy, open the frontend, create the first account, and upload a recorded track. The compose file sets PUBLIC_DISABLE_SIGNUP to "false", so registration is open by default; setting it to "true" closes it after you have made your own account. Uploads land in UPLOAD_FOLDER, which the compose file sets to /app/uploads. After the upload completes, the track should appear in the catalogue and become findable through the search box, because the write goes to PocketBase and the index goes to Meilisearch.

If you cannot run Docker, the README points at https://wanderer.to/run/installation/from-source for a bare-metal guide. The repository has a Makefile with db-build, web-install and web-build-docker targets, so the source path exists, but the README does not restate the steps.

The Meilisearch dependency is the real operational constraint

Most self-hosted apps fail softly. A background worker dies, a feed stops updating, and the rest of the product keeps working. wanderer does not behave that way, because the healthcheck gate means a search container that will not start also stops db and web from starting. If you restart the host and Meilisearch is slow to come up, the whole stack waits.

The sharper problem is index drift. Trails live in pb_data; the searchable representation lives in data.ms. Those are separate volumes with separate lifecycles. The README and the compose file do not describe a reindex command, and the repository's Makefile has no target that rebuilds the index from PocketBase. So if data.ms is deleted, restored from an older backup, or corrupted, the documented material gives you no stated way to regenerate it from the database. Treat the two volumes as a matched pair: back them up together, and restore them together.

There is a second boundary. Meilisearch is exposed on port 7700 in the compose file, and it is protected by MEILI_MASTER_KEY. If that key keeps its shipped value and the port is reachable, the index is open. The README's warning about changing the key is the only guidance on this, and it is easy to skip when the stack comes up cleanly on the first try.

How wanderer differs from a plain GPX viewer or a fitness tracker

A desktop GPX viewer such as Viking or QGIS opens files from a directory and renders them. That approach has no server, no index and no sync problem, and for a few dozen tracks it is genuinely less work than running three containers. The difference is query. A viewer shows you the file you opened; wanderer is built so that metadata and geography become filterable across the whole collection, which is what the README means by an "easily searchable catalogue".

Against a hosted fitness platform, the trade runs the other way. Strava and Komoot give you an app, a social graph and automatic syncing from a watch, and they own the data. wanderer gives you the database and nothing else. The plugins directory shows how the project bridges the two: hammerhead, komoot and strava plugins exist so tracks can be pulled in, but they are separate Go binaries installed into data/plugins, not built-in connectors. If your watch syncs only to a vendor cloud, you still need a way to get the GPX out, and the README does not describe an on-device import path.

Licence, upgrade cost and what a version bump touches

wanderer is AGPL-3.0. For someone running it at home, the practical effect is that you can use it freely and modify it. The obligation that matters is network use: if you run a modified wanderer and let other people interact with it over a network, the AGPL expects the corresponding source to be offered to those users. Running the unmodified images does not put that on you. This is a description of the licence file, not legal advice; read LICENSE in the repository if the distinction affects what you plan to do.

Upgrading is not a single pull. The compose file pins Meilisearch to v1.36.0 and leaves the two flomp images untagged, which resolves to latest. A wanderer release can therefore change the PocketBase schema, the frontend, or both, while the search engine stays fixed underneath. The releases list shows v0.20.0 on 2026-07-07, with v0.19.3 and v0.19.2 before it in the same summer, so the cadence is fast enough that you should read CHANGELOG.md before pulling. The repository also ships SECURITY.md and CONTRIBUTING.md, and the README points contributors at a roadmap project and a Crowdin translation project. The last push to the dev branch was on 2026-09-22.

Editorial conclusion

Adopt wanderer if you already keep GPX files on a disk and want them searchable on hardware you control, and you accept that the search index and the database are two separate volumes that both need backing up. Do not adopt it if you want a hosted service, a mobile-first editor, or a system that works without a Meilisearch instance. Before you commit, verify on the demo at demo.wanderer.to that the filter fields match your metadata, and check the installation page for the from-source path if you cannot run Docker.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. open-wanderer/wanderer on GitHub
3. Project website
4. README
5. Releases