Registry

commits languages

DroneDB Registry is a comprehensive aerial data management and storage platform. It provides JWT authentication, a full REST API, and integrates with Hub to offer a complete solution for hosting and sharing geospatial data.

:::tip Try it Online You can try the online hosted version of Registry (DroneDB Hub) at dronedb.app/plans with a 30-day free trial on every plan – no commitment, cancel anytime! :::

Features

Dataset Management: Create, organize, and share datasets with fine-grained permissions
Interactive Visualization: View orthophotos, point clouds, 3D models (OBJ, GLTF, GLB), and panoramas directly in the browser
User Management: Built-in user administration with role-based access control
STAC Compliance: Standard SpatioTemporal Asset Catalog API for interoperability
Public & Private Datasets: Flexible visibility controls for your data
Measurements: Interactive measurement tools on maps
Import/Export: Transfer datasets between Registry instances
On-Demand Processing: Automatic thumbnail, tile, and streaming format generation

Orthophoto Measurements

Interactive measurement tools on orthophotos:

Orthophoto Measurements

Point Cloud Measurements

Measure distances and areas directly on point clouds:

Point Cloud Measurements

Point Cloud Measurements Saved

Live Examples

Getting Started with Docker

The fastest way to get started is with Docker. Download Docker and run:

docker run -it --rm -p 5000:5000 -v ${PWD}/registry-data:/data dronedb/registry

Data will be stored in the local folder registry-data. Open http://localhost:5000 in your browser to start using the application.

Default credentials: admin / password

warning

Change the default password immediately after first login at http://localhost:5000/account

Useful Endpoints

Endpoint	Description
/scalar/v1	API Documentation (Scalar UI)
/version	Version information
/quickhealth	Quick health check (requires auth)
/health	Detailed health check (requires auth)
/hangfire	Background jobs dashboard (requires auth)
/stac	STAC Catalog root

The log file is located in registry-data/logs/registry.txt.

Getting Started Natively

Prerequisites

Install the latest version of the DroneDB library and add it to PATH
Download the latest Registry release for your platform

Running

./Registry.Web ./registry-data

Command Line Options

-a, --address              (Default: localhost:5000) Address to listen on
-c, --check                Check configuration and exit
-r, --reset-hub            Reset the Hub folder by re-creating it
--help                     Display this help screen
--version                  Display version information
Storage folder (pos. 0)    Required. Directory where Registry stores data

note

This configuration uses SQLite as the database. For production environments with high load, use MySQL/MariaDB as described in the MySQL/MariaDB Configuration section.

Change admin password

Go to /account to change password. Otherwise, you can change the admin password by changing the value of the field DefaultAdmin.Password in the appsettings.json file. After changing the password you need to restart the application.

Use MySQL / MariaDB instead of Sqlite

After the first run close the program and edit the file appsettings.json in registry-data folder:

"AuthProvider": "Mysql",
"RegistryProvider": "Mysql",
"HangfireProvider": "Mysql",
"ConnectionStrings": {
  "IdentityConnection": "Server=db;Database=RegistryAuth;Uid=registry;Pwd=password",
  "RegistryConnection": "Server=db;Database=RegistryData;Uid=registry;Pwd=password",
  "HangfireConnection": "Server=db;Database=RegistryHangfire;Uid=registry;Pwd=password;Allow User Variables=true;Connect Timeout=300"
  },

Make sure the user registry has the following permissions:

GRANT ALL PRIVILEGES ON *.* TO 'registry'@'%' IDENTIFIED BY 'password' WITH GRANT OPTION;

Then restart the application, the databases will be automatically created.

Running with docker-compose

cd docker/testing
docker-compose up -d

The stack is composed of:

MariaDB database
PHPMyAdmin, exposed on port 8080
Registry, exposed on port 5000

Running in production

You will need Git. Clone the repo and initialize submodules:

git clone https://github.com/DroneDB/Registry
cd Registry
git submodule update --init --recursive

And then run the following commands:

Linux

cd docker/production
chmod +x run.sh
./run.sh

Windows

cd docker/production
run.bat

Check that everything is running smoothly:

docker-compose ps
docker-compose logs -f

When all the containers are running, you can then open http://localhost:5000 in your browser, use admin:password as default credentials.

You can stop the application by issuing:

docker-compose down

The run.sh / run.bat script will create the default appsettings.json file, the database initialization script and start the Docker containers.

It is possible to customize the startup settings by creating a .env file in the same folder. Here's an example:

Linux (quotes are important)

MYSQL_ROOT_PASSWORD="default-root-password"
MYSQL_PASSWORD="default-mysql-password"
REGISTRY_ADMIN_MAIL="test@test.it"
REGISTRY_ADMIN_PASSWORD="password"
REGISTRY_SECRET="longandrandomsecrettobegeneratedusingcryptographicallystrongrandomnumbergenerator"
EXTERNAL_URL=""
CONTROL_SWITCH='$controlSwitch'

Windows (values without quotes)

MYSQL_ROOT_PASSWORD=default-root-password
MYSQL_PASSWORD=default-mysql-password
REGISTRY_ADMIN_MAIL=test@test.it
REGISTRY_ADMIN_PASSWORD=password
REGISTRY_SECRET=longandrandomsecrettobegeneratedusingcryptographicallystrongrandomnumbergenerator
EXTERNAL_URL=
CONTROL_SWITCH=$controlSwitch

If you want to reduce the log verbosity, you can change "Information" to "Warning" in appsettings.json:

    "LevelSwitches": {
        "$CONTROL_SWITCH": "Warning"
    }

then run

docker-compose restart registry

Info: Any changes to the configuration file need to restart the registry container

Build Docker image

If you want to build the image from scratch, you can use the following commands:

git clone https://github.com/DroneDB/Registry
cd Registry
git submodule update --init --recursive
docker build . -t dronedb/registry

Running from source

Registry is written in C# on .NET 8 platform and runs natively on Linux, Windows, and macOS. To install the latest .NET SDK see the official download page. Before building registry ensure you have ddblib in your path, if not, download the latest release and add it to PATH.

Clone the repository:

git clone https://github.com/DroneDB/Registry
cd Registry
git submodule update --init --recursive

Build the Hub interface (needs NodeJS 18+):

cd Registry.Web/ClientApp
npm install
npx webpack

Build the solution from the command line:

dotnet build

Run the tests to make sure the project is working correctly:

dotnet test

Then you can run the application:

dotnet run --project Registry.Web ./registry-data

Updating

In order to update the application, you need to replace the executable with the latest version. It will perform the required migrations and update the database at the next startup.

With docker or docker-compose, you update the application by pulling the latest image and restarting the container:

docker-compose down
docker-compose pull
docker-compose up -d

Project architecture

dronedb-registry-architecture

Key Components

Registry.Web: ASP.NET Core web application
Registry.Adapters: Database and DroneDB library adapters
Hub (Vue.js): Frontend SPA in Registry.Web/ClientApp
Hangfire: Background job processing

User Management

Registry includes a built-in user management interface accessible to administrators.

Features

Create/Delete Users: Manage user accounts
Role Management: Create custom roles and assign them to users
Organization Assignment: Control which organizations each user can access
Storage Quotas: Set per-user storage limits (when EnableStorageLimiter is enabled)
Password Management: Reset user passwords

External Authentication

For enterprise deployments, Registry supports external authentication providers via ExternalAuthUrl. When configured, local user management is disabled and authentication is delegated to the external provider.

Dataset Visibility

Datasets support three visibility levels:

Level	Description
Private	Only the owner and admins can access
Unlisted	Accessible with direct link, not listed publicly
Public	Visible to everyone, included in STAC catalog

Change visibility using:

Web UI: Dataset settings
CLI: ddb chattr +public or ddb chattr -public

STAC API

Registry implements the STAC specification for standardized geospatial data discovery.

Endpoints

Endpoint	Description
`/stac`	Root catalog with links to all public datasets
`/orgs/{org}/ds/{ds}/stac`	STAC Collection for a specific dataset

Browsing

Use the STAC Browser to explore your catalog:

https://radiantearth.github.io/stac-browser/#/external/http://localhost:5000/stac

Import & Export

Importing Datasets

Import datasets from another Registry instance via API:

POST /system/importdataset
{
  "sourceUrl": "https://source-registry.com",
  "orgSlug": "source-org",
  "dsSlug": "source-dataset",
  "targetOrgSlug": "target-org",
  "targetDsSlug": "target-dataset",
  "token": "auth-token"
}

Importing Organizations

Import entire organizations with all their datasets:

POST /system/importorg
{
  "sourceUrl": "https://source-registry.com",
  "orgSlug": "source-org",
  "targetOrgSlug": "target-org",
  "token": "auth-token"
}

Reverse Proxy Configuration

When running behind a reverse proxy (nginx, Apache, etc.), configure ExternalUrlOverride to ensure correct URL generation:

{
  "ExternalUrlOverride": "https://registry.yourdomain.com"
}

Nginx Example

server {
    listen 443 ssl;
    server_name registry.yourdomain.com;

    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        client_max_body_size 0;
    }
}

Troubleshooting

Common Issues

Container fails to start

Check logs: docker-compose logs registry
Verify database connectivity
Ensure DroneDB library is properly installed

Authentication errors

Verify Secret is set and consistent
Check token expiration settings
Clear browser cookies

File upload failures

Check MaxRequestBodySize setting
Verify storage path permissions
Check available disk space

Health Checks

Use the health endpoints to diagnose issues:

# Quick health (basic check)
curl -H "Authorization: Bearer <token>" http://localhost:5000/quickhealth

# Full health (includes database, DroneDB)
curl -H "Authorization: Bearer <token>" http://localhost:5000/health

Configuration Reference

The configuration file is appsettings.json, if not present it will be created with default values (appsettings-default.json).

AuthCookieName

The name of the authorization cookie.

info

The default value is jwtToken.

AuthProvider

The authentication provider, supported values:

Sqlite: SQLite database
Mysql: MySQL or MariaDB, (compatibility)
Mssql: Microsoft SQL Server (no migrations)

info

The default value is Sqlite

The IdentityConnection connection string should be changed accordingly

BatchTokenLength

The length of the token generated in the share endpoint.

info

The default value is 32.

CachePath

The path to the cache folder. This is used to store the generated tiles and thumbnails.

info

The default value is ./cache.

CacheProvider

The additional cache provider, supported values:

InMemory: In-memory cache provider. Example value:

{ "type": "InMemory" }

Redis: Redis cache provider. Example value:

{
   "type": "Redis",
   "settings": {
      "InstanceAddress": "localhost:5002",
      "InstanceName": "registry"
   }
}

info

The default value is null (InMemory is used).

ClearCacheInterval

The interval to clear the file cache (TimeSpan).

info

The default value is 01:00:00 (1 hour).

DefaultAdmin

The default admin user.

info

The default value is:

{
    "Email": "admin@example.com",
    "UserName": "admin",
    "Password": "password"
},

EnableStorageLimiter

Enable the storage limiter. Registry will limit the storage usage of the user based on its metadata (maxStorageMB key).

info

The default value is false.

ExternalAuthUrl

The URL of the external authentication provider.

info

The default value is null.

ExternalUrlOverride

The external URL of Registry. This is used when the application is behind a reverse proxy.

info

The default value is null.

HangfireProvider

The Hangfire provider, supported values:

InMemory: In-memory provider. Example value:
Mysql: MySQL or MariaDB

info

The default value is InMemory

The HangfireConnection connection string should be changed accordingly

MaxRequestBodySize

The maximum request body size. It sets the MultipartBodyLengthLimit of the kestrel FormOptions.

info

The default value is null (default).

RandomDatasetNameLength

The length of the random dataset name, generated when calling the share endpoint.

info

The default value is 16.

RegistryProvider

The Registry database provider, supported values:

Sqlite: SQLite database
Mysql: MySQL or MariaDB, (compatibility)
Mssql: Microsoft SQL Server (no migrations)

info

The default value is Sqlite

The RegistryConnection connection string should be changed accordingly

RevokedTokens

The list of revoked JWT tokens.

Secret

The secret used as key to generate the JWT tokens. Do not use the same secret for multiple applications.

StoragePath

The path to the storage folder.

info

The default value is ./data

ThumbnailsCacheExpiration

The expiration time of the thumbnails cache (TimeSpan).

info

The default value is 00:30:00 (30 minutes).

TilesCacheExpiration

The expiration time of the tiles cache (TimeSpan).

info

The default value is 00:30:00 (30 minutes).

TokenExpirationInDays

The number of days after which the JWT tokens will expire.

info

The default value is 7 days.

UploadBatchTimeout

The timeout for the share upload endpoint. It is the maximum time allowed between the uploads.

info

The default value is 01:00:00 (1 hour).

VisibilityCacheExpiration

The expiration time for the dataset visibility cache (TimeSpan).

info

The default value is 1.00:00:00 (1 day).

WorkerThreads

The number of worker threads used by the application. Use -1 for automatic detection.

info

The default value is -1

DatasetsPath

The path to the datasets folder.

info

The default value is ./datasets

TempPath

The path to the temporary files folder.

info

The default value is ./temp

RemoteThumbGeneratorUrl

URL of a remote thumbnail generator service for offloading thumbnail generation.

info

The default value is null

ZipMemoryThreshold

Memory threshold (in bytes) before using disk-based ZIP creation.

info

The default value is 1073741824 (1 GB)

CleanupExpiredJobsCron

Cron expression for the job that cleans up expired jobs.

info

The default value is 0 * * * * (every hour)

SyncJobStatesCron

Cron expression for the job that synchronizes job states.

info

The default value is */5 * * * * (every 5 minutes)

ProcessPendingBuildsCron

Cron expression for the job that processes pending builds.

info

The default value is * * * * * (every minute)

Getting Help

Commercial support is available. Get in touch.

Features​

Orthophoto Measurements​

Point Cloud Measurements​

Live Examples​

Getting Started with Docker​

Useful Endpoints​

Getting Started Natively​

Prerequisites​

Running​

Command Line Options​

Change admin password​

Use MySQL / MariaDB instead of Sqlite​

Running with docker-compose​

Running in production​

Linux​

Windows​

Linux (quotes are important)​

Windows (values without quotes)​

Build Docker image​

Running from source​

Updating​

Project architecture​

Key Components​

User Management​

Features​

External Authentication​

Dataset Visibility​

STAC API​

Endpoints​

Browsing​

Import & Export​

Importing Datasets​

Importing Organizations​

Reverse Proxy Configuration​

Nginx Example​

Troubleshooting​

Common Issues​

Health Checks​

Configuration Reference​

Getting Help​

Features

Orthophoto Measurements

Point Cloud Measurements

Live Examples

Getting Started with Docker

Useful Endpoints

Getting Started Natively

Prerequisites

Running

Command Line Options

Change admin password

Use MySQL / MariaDB instead of Sqlite

Running with docker-compose

Running in production

Linux

Windows

Linux (quotes are important)

Windows (values without quotes)

Build Docker image

Running from source

Updating

Project architecture

Key Components

User Management

Features

External Authentication

Dataset Visibility

STAC API

Endpoints

Browsing

Import & Export

Importing Datasets

Importing Organizations

Reverse Proxy Configuration

Nginx Example

Troubleshooting

Common Issues

Health Checks

Configuration Reference

Getting Help