Installation Guide

Prerequisites

• A Linux server (Debian 13 recommended) with a public IP
• A domain name pointed at your server (e.g. dronetm.example.org)
• Docker and Docker Compose installed
• Just task runner installed
• An S3-compatible object store (see below)

S3 Object Storage

The production stack does not bundle an S3 service - you must provide one before deploying. Drone imagery and project assets are stored here.

Options:

• Self-hosted RustFS - lightweight, single-binary S3 server you can run on the same machine or a separate host.
• Any S3-compatible provider - AWS S3, Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, self-hosted MinIO, etc.

You will need the endpoint URL, a bucket name, and an access/secret key pair. The setup wizard (just config setup) will prompt for these values.

Tip

For a simple single-server deployment, run RustFS or MinIO alongside Drone-TM on the same host and use http://localhost:9000 as the S3 endpoint.

Tip

On a fresh machine you can bootstrap Docker + Just with:

just prep machine

Quick Start (Production)

1. Clone the repository

git clone https://github.com/hotosm/drone-tm.git
cd drone-tm

2. Run interactive setup

just config setup

This wizard will prompt you for:

Prompt	Description
Domain	Your public domain (e.g. dronetm.example.org)
Cert email	Email for Let's Encrypt TLS certificates
Auth provider	hanko (HOT SSO, default) or legacy (Google OAuth)
S3 endpoint	Object storage URL (e.g. http://localhost:9000 for a local S3 server)
S3 bucket	Bucket name (default dtm-bucket)
S3 credentials	Access key and secret key for your S3-compatible store

Secrets such as SECRET_KEY and POSTGRES_PASSWORD are auto-generated.

The resulting .env file is written to the repo root. Review and adjust it as needed before deploying.

3. Deploy from a tagged release

just start prod

This will:

1. Present a menu of the most recent release tags
2. Check out the selected tag
3. Pull pre-built container images from ghcr.io/hotosm/drone-tm
4. Start all services via Docker Compose

Note

just start prod uses compose.sub.yaml, which includes the BunkerWeb reverse proxy with automatic HTTPS via Let's Encrypt. Ports 80 and 443 must be open on your server.

4. Verify

Once the services are healthy, visit https://<your-domain> in a browser.

Updating

To update to a newer release, simply run just start prod again and select the new tag. Your .env and database volumes are preserved across deploys.

Configuration Reference

Modifying the .env

After the initial just config setup, you can update individual values:

just config update-dotenv KEY value

Or regenerate the entire file (this will skip if .env already exists):

just config generate-dotenv

Key Environment Variables

Variable	Default	Description
DOMAIN	(none)	Public domain for the deployment
CERT_EMAIL	(none)	Email for Let's Encrypt certificates
AUTH_PROVIDER	legacy	hanko or legacy (Google OAuth)
HANKO_API_URL	https://dev.login.hotosm.org	Hanko endpoint (when using hanko auth)
S3_ENDPOINT_UPLOAD	http://localhost:9000	S3 endpoint for presigned uploads
S3_ENDPOINT_DOWNLOAD	same as upload	S3 endpoint for browser downloads
S3_BUCKET_NAME	dtm-bucket	S3 bucket name
POSTGRES_PASSWORD	dtm	Database password (auto-generated by setup)
SECRET_KEY	superdupersecretkey	App secret (auto-generated by setup)
ODM_ENDPOINT	http://nodeodm:9900	NodeODM processing endpoint
BACKEND_REPLICAS	4	Number of backend workers

See .env.example for the full list with inline documentation.

Architecture Overview

A production deployment runs these containers:

                        ┌─────────────┐
                   :443 │  BunkerWeb  │ :80
              HTTPS ──► │   (proxy)   │ ◄── HTTP redirect
                        └──────┬──────┘
                    ┌──────────┼──────────┐
                    ▼          ▼          ▼
              ┌──────────┐ ┌────────┐ ┌──────────┐
              │ frontend │ │backend │ │arq-worker│
              │  (HTML)  │ │  (API) │ │ (tasks)  │
              └──────────┘ └───┬────┘ └────┬─────┘
                               │           │
                          ┌────┴────┐ ┌────┴─────┐
                          │  PostGIS│ │Dragonfly │
                          │  (DB)   │ │ (cache)  │
                          └─────────┘ └──────────┘

• BunkerWeb - reverse proxy, WAF, automatic TLS
• backend - FastAPI application (scaled via BACKEND_REPLICAS)
• frontend - static SPA, copied into the proxy at startup
• arq-worker - background task queue (image processing, etc.)
• PostGIS - PostgreSQL with spatial extensions
• Dragonfly - Redis-compatible in-memory cache

Development Setup

For local development see the Developer Setup guide, which uses compose.yaml (without the production proxy) and just start all.