Maparr

Maparr is a self-hosted offline map manager for homeserver users. It provides an easy-to-use web interface to download, manage, and serve map data entirely from your local server—no internet connection required after downloading maps.

✨ Features

Admin Interface

• Map Providers: Choose from multiple map data sources (OpenStreetMap, CartoDB, OpenTopoMap, satellite imagery, and more)
• Region Selection: Download by country, state, city, or custom bounding boxes
• Download Management: Pause, resume, cancel downloads with real-time progress tracking
• Storage Management: View storage usage by region, verify map integrity, clean up unused areas
• User Management: Role-based access control with local and optional LDAP/OIDC authentication
• Layer Management: Enable/disable map layers per region (satellite, topo, trails, etc.)
• Backups & Maintenance: Automated backups, integrity checks, and scheduled maintenance

User Interface

• Offline-First Map Viewer: Instant loading, smooth panning/zooming
• Local Search: Search locations using offline geocoding database
• Bookmarks & Markers: Save favorite locations, custom pins, named markers
• GPX Support: Import/export GPX tracks and waypoints
• Measurement Tools: Measure distances and areas
• Shareable Links: Share map views with other users on the same server
• Print Maps: Generate printable maps of your current view
• Dark Mode: Optional dark theme for comfortable viewing

Technical Features

• Docker-First: Single-container deployment with multi-arch support
• REST API: Full API for automation and integrations
• Webhooks: Event notifications for download completion, updates, etc.
• Observability: Prometheus metrics, structured logging, health monitoring
• Low Resource Usage: Optimized for Raspberry Pi-class hardware
• Responsive Design: Works on desktops, tablets, and mobile devices

🚀 Quick Start

Docker Compose (Recommended)

services:
  maparr:
    image: ghcr.io/fyrek1d/maparr:latest
    container_name: maparr
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - maparr_data:/app/data
    environment:
      - MAPARR_DATABASE_URL=sqlite:////app/data/maparr.db
      - MAPARR_JWT_SECRET=change-me-to-a-long-random-string
      # First-run admin bootstrap:
      - MAPARR_BOOTSTRAP_ADMIN_USERNAME=admin
      - MAPARR_BOOTSTRAP_ADMIN_PASSWORD=${MAPARR_BOOTSTRAP_ADMIN_PASSWORD}
      - MAPARR_BOOTSTRAP_ADMIN_EMAIL=admin@localhost
      - MAPARR_ALLOW_REGISTRATION=false

volumes:
  maparr_data:

Or clone the repo and build locally:

git clone https://github.com/fyrek1d/maparr.git
cd maparr
docker compose up -d

Access the admin interface at http://localhost:8000 and configure your first map download.

📚 Documentation

See the Documentation Index.

📦 Map Providers

Maparr supports multiple map providers with offline licensing:

Provider	Type	License	Offline
OpenStreetMap	Basemap	ODbL	✅
OpenStreetMap HOT	Basemap	ODbL	✅
CartoDB Voyager	Basemap	CC BY-SA	✅
OpenTopoMap	Topographic	CC BY-SA	✅
CycleOSM	Cycling	ODbL	✅
Waymarked Trails	Overlay	ODbL	✅
Esri World Imagery	Satellite	Esri Terms	⚠️ Check license

Custom Providers

You can add custom map providers via the admin interface:

{
  "name": "My Custom Map",
  "url_template": "https://tiles.example.com/{z}/{x}/{y}.png",
  "attribution": "© My Map Provider",
  "license": "Custom License"
}

🔒 Authentication

Maparr supports multiple authentication methods:

• Local Users: Username/password with bcrypt hashing
• OpenID Connect: Connect to identity providers like Authelia, Keycloak
• LDAP/Active Directory: Integrate with existing directory services

📊 System Requirements

• CPU: 1 core minimum, 2+ recommended
• RAM: 512MB minimum, 1GB+ recommended
• Storage: 1GB minimum + map data (typically 1-10GB per region)
• Network: Initial setup only; works offline afterwards
• OS: Linux, Docker support (Windows/macOS via Docker)

🤝 Contributing

We welcome contributions! Please see Contributing Guide for details.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Natural Earth for geographic data
• Leaflet for the mapping library
• OpenStreetMap contributors
• All map data providers for their offline-friendly licenses

---

Made with ❤️ for the self-hosting community