Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/opengisch/qfieldcloud/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

QFieldCloud is a Django-based service designed to synchronize projects and data between QGIS (+ QFieldSync plugin) and QField. While OPENGIS.ch offers a hosted solution at qfield.cloud, you can also self-host your own QFieldCloud instance.

​
Hosted vs Self-Hosted

​
Hosted Solution

The hosted version at app.qfield.cloud is:
  • Fully managed and maintained by OPENGIS.ch
  • Integrated by default into QField
  • Requires no infrastructure setup or maintenance
  • Includes professional support options
  • Ideal for getting up and running quickly

​
Self-Hosted Solution

Self-hosting QFieldCloud is suitable when you:
  • Need complete control over your data and infrastructure
  • Have specific security or compliance requirements
  • Want to integrate with existing on-premise systems
  • Require custom configurations or modifications
  • Have the technical resources to manage the infrastructure
QFieldCloud is designed to work with externally managed services for its database (PostgreSQL), Object Storage (S3), and mailing provider.For small self-hosted environments, you may run QFieldCloud on a single server using docker-compose.override.standalone.yml, but this is entirely at your own risk.The maintainers do not recommend and do not guarantee that the standalone version will always work between versions, and will close all issues regarding standalone deployment without further explanation.

​
Architecture

QFieldCloud consists of several key components:

​
Core Services

  • app: Django application server running with Gunicorn
  • nginx: Reverse proxy handling HTTPS/TLS termination and static file serving
  • worker_wrapper: Background job processor for QGIS operations
  • qgis: QGIS worker container for processing geospatial data
  • memcached: Caching layer for improved performance
  • ofelia: Cron job scheduler for periodic tasks
  • certbot: Automatic SSL certificate management via Let’s Encrypt

​
External Dependencies (Production)

For production deployments, you should use external managed services:
  • PostgreSQL/PostGIS: Database for storing application data
  • S3-compatible storage: Object storage for project files (AWS S3, MinIO, etc.)
  • SMTP server: Email delivery service

​
Standalone Services (Development/Testing Only)

For local development or small standalone deployments:
  • db: PostgreSQL/PostGIS database container
  • minio: S3-compatible object storage
  • smtp4dev: Local email testing server
  • webdav: Alternative storage backend (optional)

​
System Requirements

​
Minimum Requirements

  • Docker Engine 20.10 or later
  • Docker Compose 2.0 or later
  • 4 GB RAM (8 GB recommended)
  • 20 GB disk space for application and dependencies
  • Additional storage for project data and backups

​
Network Requirements

  • Public domain name (for Let’s Encrypt SSL certificates)
  • Open ports:
    • 80 (HTTP) - for Let’s Encrypt certificate validation
    • 443 (HTTPS) - for secure access to QFieldCloud
    • 5432 (PostgreSQL) - if using external database
  • 8+ GB RAM
  • 4+ CPU cores
  • SSD storage for database and application
  • External managed PostgreSQL database
  • External S3-compatible storage with versioning enabled
  • External SMTP service for reliable email delivery
  • Regular automated backups

​
Infrastructure Components

Based on the testdriven.io Django dockerization guide.

​
Port Configuration

ServicePortConfigurationLocalDevelopmentProduction
nginx http80WEB_HTTP_PORT✓✓✓
nginx https443WEB_HTTPS_PORT✓✓✓
django http8011DJANGO_DEV_PORT✓✗✗
postgres5433HOST_POSTGRES_PORT✓✓✓
minio API8009MINIO_API_PORT✓✗✗
minio browser8010MINIO_BROWSER_PORT✓✗✗
smtp web8012SMTP4DEV_WEB_PORT✓✗✗
smtp25SMTP4DEV_SMTP_PORT✓✗✗
imap143SMTP4DEV_IMAP_PORT✓✗✗

​
Security Considerations

​
Essential Security Steps

  1. Change default secrets: Update SECRET_KEY and SALT_KEY in .env
  2. Set strong database password: Change POSTGRES_PASSWORD
  3. Disable debug mode: Set DEBUG=0 in production
  4. Configure allowed hosts: Set DJANGO_ALLOWED_HOSTS to your domain(s)
  5. Use HTTPS: Configure SSL certificates (Let’s Encrypt recommended)
  6. Enable email verification: Set ACCOUNT_EMAIL_VERIFICATION=mandatory
  7. Secure storage credentials: Use strong passwords for MinIO or S3 credentials
  8. Regular updates: Keep Docker images and dependencies up to date

​
Production Deployment Checklist

  • All default passwords changed
  • DEBUG mode disabled (DEBUG=0)
  • Valid SSL certificate configured
  • Database backups configured
  • Object storage backups enabled
  • SMTP service configured and tested
  • Monitoring and logging in place
  • Firewall rules configured
  • Resource limits set in docker-compose
  • Regular update schedule established

​
Getting Started

To begin deploying QFieldCloud:
  1. Review the Docker Setup guide for step-by-step installation instructions
  2. Configure your Environment Variables
  3. Set up SSL Certificates
  4. Configure Database and Storage

​
Support

​
Hosted Service Support

For questions about the hosted service at app.qfield.cloud, submit a ticket at tickets.qfield.cloud.

​
Self-Hosted Support

For self-hosted issues, use the GitHub issues at github.com/opengisch/qfieldcloud/issues.

​
Feature Requests

Visit ideas.qfield.org to submit new feature requests or upvote existing ones.

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us