wanderer

Wanderer is a self‑hosted trail catalog built to ingest, index, and surface GPS data for hikers, cyclists, and outdoor enthusiasts. At its core it exposes a REST‑like API that accepts GPX/TCX/KML uploads, enriches them with metadata (tags, categories, difficulty, etc.), and stores the result in a searchable database. The web front‑end is a single‑page application that consumes this API and renders interactive maps using OpenStreetMap tiles. From a developer’s point of view, Wanderer is designed to be plug‑in friendly and lightweight enough for deployment in a containerized microservice stack.

• Backend – Written in Go, leveraging the gin web framework for routing and JSON handling. Go’s static binaries make it ideal for container images that can be built once and run on any Linux distribution.
• Search Engine – Uses MeiliSearch, an open‑source full‑text search engine. The backend exposes a thin wrapper around the MeiliSearch client, allowing developers to adjust ranking rules or add custom attributes without touching core code.
• Database – PostgreSQL stores the canonical trail records, user accounts, and relational metadata. The schema is intentionally simple: a trails table with geometry columns (PostGIS) for spatial queries, and auxiliary tables for tags, lists, and user preferences.
• Map Rendering – The front‑end is built with React (Vite) and uses react-leaflet to display vector tiles. All map data is served from the same domain, avoiding cross‑origin issues when deployed behind a reverse proxy.
• Containerization – A single docker-compose.yml pulls three images: the Go API, MeiliSearch, and PostgreSQL. The compose file also exposes environment variables for secrets (e.g., MEILI_MASTER_KEY) and CORS origin handling.

• Trail Upload & Parsing – Accepts GPX, TCX, and KML files; parses waypoints, segments, and elevation data. The API returns a unique trail ID that can be referenced programmatically.
• Metadata Enrichment – Exposes endpoints to add tags, set difficulty levels, or create custom lists. Bulk import is supported via CSV/JSON payloads for large catalogues.
• Search & Filtering – The search API supports full‑text queries, spatial bounds (bbox), and boolean filters on tags or user lists. Developers can tweak MeiliSearch’s ranking rules to prioritize distance, elevation gain, or recency.
• Webhooks – When a trail is created or updated, the API can emit a webhook to an external service (e.g., Slack, custom analytics).
• Authentication – Built‑in JWT support with role‑based access control; the API can be extended to integrate with OAuth providers or SSO solutions.

Wanderer is intentionally minimalistic to fit into a Docker‑centric environment. The official compose file requires only three services, each with their own volume for persistence. For production, developers can:

• Run the stack behind an Nginx or Traefik reverse proxy to enable HTTPS and HTTP/2.
• Scale MeiliSearch by running a single‑node cluster; the API can be replicated behind a load balancer.
• Use Kubernetes manifests (Helm chart available in the repo) to deploy on managed clusters, taking advantage of StatefulSets for PostgreSQL and persistent volumes.
• Leverage CI/CD pipelines to rebuild the Go binary and push updated images, ensuring zero‑downtime deployments.

The modular architecture encourages third‑party contributions. The API is fully documented in OpenAPI format, making it straightforward to generate SDKs for Go, Python, or JavaScript. Developers can write custom plugins by extending the MeiliSearch index with new fields or by hooking into the upload pipeline to run custom validation. The front‑end is open source; contributors can add new map layers, integrate additional GIS services (e.g., elevation models), or replace the React stack with Vue or Svelte without touching the backend.

• Configuration – All tunable parameters are exposed as environment variables; the compose file includes sensible defaults.
• Documentation – The official site hosts a comprehensive guide covering installation, API reference, and best practices.
• Community – A dedicated Discord server offers real‑time support; the issue tracker is actively maintained, and pull requests are merged rapidly.
• Licensing – The AGPLv3 license ensures that any derivative work remains open source, which is attractive for projects that value transparency and community contribution.

• Outdoor Clubs & NGOs – Host a private trail catalog for members, with custom tagging (e.g., accessibility, flora).
• Tourism Boards – Publish a searchable trail map that integrates with local accommodation APIs.
• Data Scientists – Pull trail metadata into analytical pipelines for route optimization or environmental impact studies.
• App Developers – Embed Wanderer’s API into mobile apps to provide offline trail lists and dynamic route planning.

Wanderer offers a lightweight, self‑hosted alternative to commercial trail services. Its Go backend guarantees low latency and minimal resource usage, while MeiliSearch delivers fast full‑text search without the overhead of Elasticsearch. The open source license and active community reduce vendor lock‑in, and the Docker‑first approach simplifies CI/CD. For developers who need a customizable