Skip to main content

​
Introduction to QFieldCloud

QFieldCloud is a Django-based SaaS platform designed to synchronize projects and data between QGIS (+ QFieldSync plugin) and QField mobile app. It enables seamless field data collection with change tracking, team management, and online-offline work capabilities.

​
What is QFieldCloud?

QFieldCloud allows you to:
  • Synchronize field data with your spatial infrastructure
  • Track changes with versioned file storage and delta-based synchronization
  • Collaborate with teams through role-based access control
  • Work offline in the field and sync when connected
  • Manage projects through a web interface or REST API

​
Key Concepts

​
Projects

Projects are the core organizational unit in QFieldCloud. Each project contains:
  • QGIS project files (.qgs, .qgz)
  • GIS datasets (GeoPackage, Shapefiles, Rasters)
  • Field-collected data and attachments
  • Team member roles and permissions

​
Users and Organizations

QFieldCloud supports two types of accounts:
  • Persons: Individual user accounts
  • Organizations: Team accounts with multiple members
Projects can be owned by either persons or organizations, with configurable visibility (public or private).

​
Synchronization

QFieldCloud uses delta-based synchronization to efficiently transfer only the changes between QGIS desktop and QField mobile:
  1. Package: QGIS project is packaged for field use via QFieldSync plugin
  2. Upload: Project files are uploaded to QFieldCloud
  3. Download: QField mobile app downloads the project
  4. Collect: Data is collected offline in the field
  5. Sync: Changes are pushed back to QFieldCloud
  6. Apply: QGIS desktop pulls the updates

​
Storage

QFieldCloud supports multiple storage backends:
  • S3-compatible storage (default with MinIO)
  • WebDAV (including NextCloud integration)
  • Custom storage backends
All project files are versioned, enabling rollback and change tracking.

​
Architecture Overview

QFieldCloud is built with Django and designed to run as a containerized application using Docker.

​
Core Components

Web Application (app)
  • Django application serving the REST API
  • Gunicorn WSGI server for production
  • Handles authentication, project management, and file operations
NGINX Reverse Proxy (nginx)
  • SSL/TLS termination
  • Static file serving
  • Request routing and load balancing
QGIS Worker (worker_wrapper + qgis)
  • Background job processing
  • QGIS server operations
  • Project validation and transformation
  • Docker-in-Docker architecture for isolation
Database (db)
  • PostgreSQL with PostGIS extension
  • Stores user accounts, projects, permissions
  • Manages synchronization metadata
Object Storage
  • Versioned file storage (MinIO or S3)
  • Stores project files and attachments
  • Supports delta-based change tracking
Cache (memcached)
  • Session storage
  • API response caching
  • Performance optimization

​
Authentication

QFieldCloud supports multiple authentication methods:
  • Password-based login (configurable)
  • OAuth2/OIDC providers (Google, GitHub, Keycloak)
  • API tokens with configurable expiration (default: 720 hours)
Tokens are client-specific:
  • Browser tokens
  • QField mobile tokens (single-token per device)
  • QFieldSync plugin tokens
  • CLI/SDK tokens

​
API Access

QFieldCloud provides a REST API for programmatic access:
  • Base URL: https://your-host/api/v1/
  • Authentication: Token-based (Authorization header)
  • Documentation: Available at /swagger/ endpoint
  • Status: Monitor health at /api/v1/status/
curl -H "Authorization: Token YOUR_API_TOKEN" \
  https://qfield.cloud/api/v1/projects/

​
Deployment Options

​
Hosted Service

The easiest way to use QFieldCloud is through the official hosted service at qfield.cloud, operated by OPENGIS.ch. This is the default service integrated into QField mobile app. Benefits:
  • No infrastructure management
  • Automatic updates and backups
  • Integrated with QField by default
  • Professional support available

​
Self-Hosted

For organizations requiring data sovereignty or custom configurations, QFieldCloud can be self-hosted:
  • Full control over data and infrastructure
  • Custom authentication providers
  • Integration with existing storage systems
  • Suitable for air-gapped or private networks
Self-hosted deployments require expertise in Docker, PostgreSQL, and web server management. The maintainers recommend using external managed services for production databases and object storage.

​
Next Steps

Quickstart

Get started with your first QFieldCloud project

Installation

Deploy your own QFieldCloud instance

Build docs developers (and LLMs) love

Get started for freeTalk to us