Wanderer Deployment and Usage Guide

1. Prerequisites

Before installing Wanderer, ensure you have the following:

Required:

Docker and Docker Compose (recommended method)
OR Node.js 18+ with npm/pnpm (for bare-metal installation)

Optional (for development):

Git for cloning the repository
A modern web browser (Chrome, Firefox, Safari, Edge)
Basic understanding of containerization concepts

Accounts (optional but recommended):

Map tile provider account (OpenStreetMap, MapTiler, etc.) for custom map tiles
Email service account (SMTP) for user notifications

2. Installation

Docker Compose (Recommended)

# Download the docker compose file
wget https://raw.githubusercontent.com/open-wanderer/wanderer/main/docker-compose.yml

# Build and launch the containers
docker compose up -d

The first startup can take up to 90 seconds as services initialize. Once ready, access the frontend at http://localhost:3000.

Bare-Metal Installation

For detailed bare-metal installation instructions, refer to the official documentation. The general process involves:

Clone the repository
Install backend dependencies
Set up the database (PocketBase)
Configure the search engine (Meilisearch)
Build and run the Svelte frontend

3. Configuration

Environment Variables

Configure Wanderer via environment variables in your docker-compose.yml:

Essential variables to set:

environment:
  - ORIGIN=http://localhost:3000  # Change to your actual domain
  - MEILI_MASTER_KEY=your-secure-key-here  # REQUIRED for production

Important Notes:

If not hosting at http://localhost:3000, must change the ORIGIN variable to avoid CORS errors
For production environments, must change the MEILI_MASTER_KEY variable from default
The default configuration uses SQLite for simplicity; for production consider PostgreSQL

Database Configuration

Wanderer uses PocketBase as its backend database. The Docker setup automatically configures:

SQLite database at /pb/pb_data/data.db
Admin interface accessible at http://localhost:8090/_/
Default admin credentials should be changed on first login

Search Configuration

Meilisearch provides the search functionality:

Accessible at http://localhost:7700
Master key configured via MEILI_MASTER_KEY
Indexes automatically created on first run

4. Build & Run

Development Mode

For development work on Wanderer:

# Clone the repository
git clone https://github.com/open-wanderer/wanderer.git
cd wanderer

# Install dependencies (if working on frontend)
cd web
npm install  # or pnpm install

# Run development server
npm run dev

Production Build

To build for production:

# Build the frontend
cd web
npm run build

# The built files will be in the 'build' directory
# These are automatically served by the Docker setup

5. Deployment

Platform Recommendations

Based on Wanderer's tech stack (Svelte frontend, PocketBase backend, Meilisearch):

Recommended Platforms:

VPS/Dedicated Server (DigitalOcean, Linode, Vultr, Hetzner)
- Full control over configuration
- Can use Docker Compose as-is
- Example minimum specs: 2GB RAM, 2 vCPUs, 20GB SSD
Docker-Capable Hosting (Railway, Fly.io, Render)
- Easy deployment of Docker Compose setups
- Built-in scaling options
- Simplified networking
Traditional VPS with Manual Setup
- Install Docker and Docker Compose
- Set up reverse proxy (nginx, Caddy)
- Configure SSL certificates (Let's Encrypt)

Deployment Steps

Prepare your server:

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker and Docker Compose
sudo apt install docker.io docker-compose -y

Deploy Wanderer:

# Create deployment directory
mkdir ~/wanderer && cd ~/wanderer

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

# Edit configuration
nano docker-compose.yml  # Update ORIGIN and MEILI_MASTER_KEY

# Start services
docker compose up -d

Set up reverse proxy (nginx example):

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Configure SSL with Let's Encrypt:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Backup Strategy

Regularly backup:

PocketBase data: /pb/pb_data/ directory
Meilisearch data: Configured data directory
Uploaded files: Check volume mounts in docker-compose.yml

6. Troubleshooting

Common Issues and Solutions

1. CORS Errors

Error: Cross-Origin Request Blocked

Solution: Ensure the ORIGIN environment variable matches your exact frontend URL (including protocol and port).

2. Slow Initial Startup Solution: First startup takes up to 90 seconds as services initialize. Check logs:

docker compose logs -f

3. Search Not Working Solution: Verify Meilisearch is running and accessible:

# Check Meilisearch health
curl http://localhost:7700/health

4. Database Connection Issues Solution: Check PocketBase logs:

docker compose logs pb

5. Map Tiles Not Loading Solution:

Check internet connectivity
Verify no firewall blocking tile server access
Consider setting up a local tile server for offline use

6. File Upload Failures Solution:

Check disk space
Verify volume permissions in Docker
Ensure upload directory exists and is writable

7. Performance Issues Solution:

Increase Docker resource limits
Consider switching from SQLite to PostgreSQL for production
Implement caching layer (Redis)

Getting Help

Check the official documentation
Join the Developer Discord
Review existing GitHub issues
Try the live demo to verify expected behavior

Logs and Diagnostics

Access service logs:

# All services
docker compose logs

# Specific service
docker compose logs web
docker compose logs pb
docker compose logs meilisearch

# Follow logs in real-time
docker compose logs -f

Check service status:

docker compose ps
docker compose top

How to Deploy & Use wanderer