Deploying Wanderer

Introduction

Wanderer is a self-hosted trail and hiking database application that allows outdoor enthusiasts to track their adventures, log hikes, and build a personal collection of trails. Whether you’re an avid hiker, trail runner, or just enjoy exploring the outdoors, Wanderer provides a beautiful interface for documenting your journeys.

Built with modern web technologies, Wanderer offers features for importing GPS tracks, viewing elevation profiles, adding photos, and tracking statistics across your adventures. It’s a privacy-focused alternative to commercial tracking apps, keeping your location data under your control.

Key highlights of Wanderer:

• Trail Database: Build your personal collection of trails and routes
• GPS Import: Import GPX files from GPS devices and apps
• Elevation Profiles: Visualize elevation changes along your routes
• Photo Integration: Add photos to document your adventures
• Statistics Tracking: Track distance, elevation gain, and more
• Map Visualization: View trails on interactive maps
• Search and Filter: Find trails by difficulty, distance, or location
• Multi-User Support: Share trails with family and friends
• Offline Ready: Access your trail data without internet
• Privacy Focused: Your location data stays on your server
• Open Source: Fully open source and self-hostable

This guide walks through deploying Wanderer on Klutch.sh using Docker, configuring storage for your trail data, and setting up the application for production use.

Why Deploy Wanderer on Klutch.sh

Deploying Wanderer on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Wanderer without complex orchestration. Push to GitHub, and your trail database deploys automatically.

Persistent Storage: Attach persistent volumes for your trail data, photos, and database. Your adventure logs survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your trail data from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Access Anywhere: View and plan your adventures from any device, whether at home or on the trail with cell service.

Scalable Resources: Allocate CPU and memory based on your collection size and usage patterns.

Custom Domains: Assign a custom domain for your personal trail database.

Prerequisites

Before deploying Wanderer on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Wanderer configuration
• Basic familiarity with Docker and containerization concepts
• GPX files from your GPS device or tracking app (optional)
• (Optional) A custom domain for your Wanderer instance

Preparing Your Repository

To deploy Wanderer on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

wanderer-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/flomp/wanderer:latest

# Set environment variables
ENV ORIGIN=${ORIGIN}
ENV MEILI_URL=${MEILI_URL:-http://localhost:7700}
ENV MEILI_MASTER_KEY=${MEILI_MASTER_KEY}

# Database configuration
ENV DATABASE_URL=${DATABASE_URL}

# Expose the web interface port
EXPOSE 3000

Multi-Container Setup

Wanderer typically requires MeiliSearch for full-text search. For a complete setup, you may need to deploy MeiliSearch separately or use an all-in-one image if available.

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
ORIGIN	Yes	-	Public URL of your instance
DATABASE_URL	Yes	-	Database connection string
MEILI_URL	No	-	MeiliSearch URL for search functionality
MEILI_MASTER_KEY	Conditional	-	MeiliSearch master key
BODY_SIZE_LIMIT	No	10M	Maximum upload size for GPX files

Deploying Wanderer on Klutch.sh

Once your repository is prepared, follow these steps to deploy Wanderer:

Set Up Database

Wanderer requires a database. You can either:

• Use a managed PostgreSQL service
• Deploy PostgreSQL as a separate app on Klutch.sh

Ensure you have your database connection string ready.

Set Up MeiliSearch (Optional)

For full-text search functionality:

• Deploy MeiliSearch as a separate app
• Note the URL and master key

Push Your Repository to GitHub

Initialize your repository and push to GitHub. Ensure your Dockerfile is in the root of your repository.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “wanderer” or “trail-tracker”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Wanderer Dockerfile.

Configure HTTP Traffic

Wanderer serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

In the environment variables section, add:

Variable	Value
ORIGIN	https://your-app-name.klutch.sh
DATABASE_URL	Your database connection string
MEILI_URL	Your MeiliSearch URL (if using)
MEILI_MASTER_KEY	Your MeiliSearch key (if using)

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/data	10 GB	Application data and uploads
/app/uploads	20 GB	Photos and GPX files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Wanderer container
• Provision an HTTPS certificate

Access Wanderer

Once deployment completes, access your Wanderer instance at https://your-app-name.klutch.sh.

Initial Setup

Creating Your Account

When you first access Wanderer:

1. Click on the registration link
2. Create your administrator account
3. Complete the setup wizard

Adding Your First Trail

Start documenting your adventures:

1. Click Add Trail or New Trail
2. Upload a GPX file from your GPS device
3. Or manually create a trail by drawing on the map
4. Add details like name, description, and difficulty
5. Add photos from your hike
6. Save your trail

Importing GPX Files

Import existing GPS tracks:

1. Export GPX files from your tracking app (Strava, Komoot, etc.)
2. Navigate to import in Wanderer
3. Select your GPX file
4. Review and edit trail details
5. Save to your collection

Managing Your Trails

Organizing Collections

Keep your trails organized:

• Create collections for different regions
• Tag trails by activity type
• Filter by difficulty or distance
• Search by name or location

Trail Details

Each trail can include:

• Name and description
• Distance and elevation statistics
• Difficulty rating
• Photos and media
• Personal notes
• GPS track visualization

Statistics Dashboard

Track your progress:

• Total distance hiked
• Total elevation gained
• Number of trails completed
• Activity over time

Sharing Trails

With Other Users

Share your adventures:

1. Add users to your Wanderer instance
2. Share specific trails or collections
3. Collaborate on trail documentation

Export Options

Export your data:

• GPX export for GPS devices
• Share links for specific trails
• Backup your entire collection

Production Best Practices

Security Recommendations

• Strong Passwords: Use secure passwords for all accounts
• Database Security: Use strong database credentials
• Regular Backups: Back up your database and uploads

Storage Management

• Photo Optimization: Consider optimizing large photos
• GPX File Size: Large GPX files may need adjustment
• Volume Sizing: Plan for your expected collection size

Performance

• MeiliSearch: Enable search for large collections
• Resource Allocation: Increase resources for large databases
• Caching: Configure caching for better performance

Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container crashes on startup.

Solutions:

• Verify database connection string
• Check all required environment variables
• Review logs for specific errors

GPX Import Failing

Symptoms: Files don’t import or show errors.

Solutions:

• Verify GPX file format is valid
• Check file size limits
• Ensure sufficient disk space

Maps Not Loading

Symptoms: Map tiles don’t display.

Solutions:

• Check network connectivity
• Verify map tile provider settings
• Clear browser cache

Search Not Working

Symptoms: Search returns no results.

Solutions:

• Verify MeiliSearch is running
• Check MeiliSearch connection settings
• Rebuild search index

Additional Resources

• Wanderer GitHub Repository
• MeiliSearch Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Wanderer on Klutch.sh gives you a beautiful, self-hosted trail database with automatic builds, persistent storage, and secure HTTPS access. The combination of Wanderer’s intuitive interface and Klutch.sh’s deployment simplicity means you can focus on exploring the outdoors rather than managing infrastructure.

Whether you’re documenting local day hikes or tracking multi-day backpacking trips, Wanderer on Klutch.sh provides a reliable, private solution for preserving your outdoor memories and planning future adventures.