Environment Configuration

Overview

QFieldCloud uses environment variables for configuration. All settings are defined in the .env file at the root of the project. This page documents the most important configuration options.

Copy .env.example to .env and modify the values according to your deployment requirements.

General Settings

DEBUG

Type: Boolean (0 or 1)
Default: 1
Production Value: 0 Enables or disables Django debug mode.

Always set to 0 in production! Debug mode exposes sensitive information and should never be enabled on public-facing servers.

DEBUG=0

QFIELDCLOUD_HOST

Type: String
Default: localhost
Required: Yes Main hostname of your QFieldCloud instance. Must not include http://, https://, trailing slash, or port number.

QFIELDCLOUD_HOST=qfield.yourcompany.com

ENVIRONMENT

Type: String
Default: development
Options: development, staging, test, production Defines the environment where QFieldCloud runs. Used for logging, monitoring, and feature flags.

ENVIRONMENT=production

Security Settings

SECRET_KEY

Type: String
Default: change_me
Required: Yes Django secret key used for cryptographic signing. Must be unique and kept secret.

Critical Security Setting! Generate a strong random key and never share it publicly.

# Generate with: pwgen -sn 128
SECRET_KEY=your-very-long-random-secret-key-here

SALT_KEY

Type: String
Default: 0123456789abcdefghijklmnopqrstuvwxyz
Required: Yes Key used for cryptographic operations on encrypted fields.

# Generate with: pwgen -sn 128
SALT_KEY=your-very-long-random-salt-key-here

Certificate Settings

QFIELDCLOUD_TLS_CERT

Type: File Path
Default: /etc/nginx/certs/${QFIELDCLOUD_HOST}.pem Path to TLS certificate file within the nginx container.

# For Let's Encrypt
QFIELDCLOUD_TLS_CERT="/etc/letsencrypt/live/${QFIELDCLOUD_HOST}/fullchain.pem"

# For self-signed certificate
QFIELDCLOUD_TLS_CERT="/etc/nginx/certs/${QFIELDCLOUD_HOST}.pem"

QFIELDCLOUD_TLS_KEY

Type: File Path
Default: /etc/nginx/certs/${QFIELDCLOUD_HOST}-key.pem Path to TLS private key file within the nginx container.

# For Let's Encrypt
QFIELDCLOUD_TLS_KEY="/etc/letsencrypt/live/${QFIELDCLOUD_HOST}/privkey.pem"

# For self-signed certificate
QFIELDCLOUD_TLS_KEY="/etc/nginx/certs/${QFIELDCLOUD_HOST}-key.pem"

QFIELDCLOUD_TLS_DHPARAMS

Type: File Path
Default: /etc/nginx/dhparams/ssl-dhparams.pem Path to Diffie-Hellman parameters file. Leave empty to disable.

QFIELDCLOUD_TLS_DHPARAMS="/etc/nginx/dhparams/ssl-dhparams.pem"

Let’s Encrypt Settings

LETSENCRYPT_EMAIL

Type: Email
Default: [email protected]
Required: Yes (for Let’s Encrypt) Email address used for Let’s Encrypt registration and recovery.

LETSENCRYPT_EMAIL=[email protected]

LETSENCRYPT_RSA_KEY_SIZE

Type: Integer
Default: 4096 RSA key size for Let’s Encrypt certificates.

LETSENCRYPT_RSA_KEY_SIZE=4096

LETSENCRYPT_STAGING

Type: Boolean (0 or 1)
Default: 1 Use Let’s Encrypt staging environment (avoids rate limits during testing).

# For testing
LETSENCRYPT_STAGING=1

# For production
LETSENCRYPT_STAGING=0

Database Settings

POSTGRES_USER

Type: String
Default: qfieldcloud_db_admin PostgreSQL connection user. Must have permissions to create and modify the database.

POSTGRES_USER=qfieldcloud_db_admin

POSTGRES_PASSWORD

Type: String
Default: 3shJDd2r7Twwkehb
Required: Yes PostgreSQL connection password.

Change this immediately! The default password is publicly known.

# Generate with: pwgen -sn 16
POSTGRES_PASSWORD=your-strong-database-password

POSTGRES_DB

Type: String
Default: qfieldcloud_db PostgreSQL database name. Will be created if it doesn’t exist.

POSTGRES_DB=qfieldcloud_db

POSTGRES_HOST

Type: String
Default: db PostgreSQL host. Use db for standalone deployment or your external database hostname.

# Standalone
POSTGRES_HOST=db

# External database
POSTGRES_HOST=postgres.yourcompany.com

POSTGRES_PORT

Type: Integer
Default: 5432 PostgreSQL port.

POSTGRES_PORT=5432

POSTGRES_SSLMODE

Type: String
Default: prefer
Options: disable, allow, prefer, require, verify-ca, verify-full PostgreSQL SSL mode. Use require or higher for production.

# For production with external database
POSTGRES_SSLMODE=require

# For local development
POSTGRES_SSLMODE=prefer

Storage Settings

STORAGES

Type: JSON
Required: Yes Defines storage backends for QFieldCloud. Supports S3, MinIO, and WebDAV.

Default S3/MinIO Configuration

STORAGES='{
    "default": {
        "BACKEND": "qfieldcloud.filestorage.backend.QfcS3Boto3Storage",
        "OPTIONS": {
            "access_key": "minioadmin",
            "secret_key": "minioadmin",
            "bucket_name": "qfieldcloud-local",
            "region_name": "",
            "endpoint_url": "http://172.17.0.1:8009"
        },
        "QFC_IS_LEGACY": false
    }
}'

AWS S3 Configuration

STORAGES='{
    "default": {
        "BACKEND": "qfieldcloud.filestorage.backend.QfcS3Boto3Storage",
        "OPTIONS": {
            "access_key": "YOUR_AWS_ACCESS_KEY",
            "secret_key": "YOUR_AWS_SECRET_KEY",
            "bucket_name": "your-qfieldcloud-bucket",
            "region_name": "eu-central-1",
            "endpoint_url": ""
        },
        "QFC_IS_LEGACY": false
    }
}'

WebDAV Configuration

STORAGES='{
    "default": {
        "BACKEND": "qfieldcloud.filestorage.backend.QfcWebDavStorage",
        "OPTIONS": {
            "webdav_url": "http://user:password@webdav",
            "public_url": "http://webdav",
            "basic_auth": "user:password"
        },
        "QFC_IS_LEGACY": false
    }
}'

STORAGES_PROJECT_DEFAULT_STORAGE

Type: String
Default: (empty, uses default) Default storage backend for new projects. Must be a key from STORAGES.

STORAGES_PROJECT_DEFAULT_STORAGE=default

STORAGES_PROJECT_DEFAULT_ATTACHMENTS_STORAGE

Type: String
Default: (empty, uses default) Default attachments storage for new projects.

STORAGES_PROJECT_DEFAULT_ATTACHMENTS_STORAGE=default

Nginx Settings

WEB_HTTP_PORT

Type: Integer
Default: 80 Public HTTP port.

WEB_HTTP_PORT=80

WEB_HTTPS_PORT

Type: Integer
Default: 443 Public HTTPS port.

WEB_HTTPS_PORT=443

NGINX_ERROR_LOG_LEVEL

Type: String
Default: error
Options: debug, info, notice, warn, error, crit, alert, emerg Nginx error log level.

NGINX_ERROR_LOG_LEVEL=error

NGINX_CLIENT_MAX_BODY_SIZE

Type: String
Default: 10g Maximum allowed size of client request body.

NGINX_CLIENT_MAX_BODY_SIZE=10g

NGINX_PROXY_TIMEOUTS

NGINX_PROXY_CONNECT_TIMEOUT=5s
NGINX_PROXY_READ_TIMEOUT=300s
NGINX_PROXY_SEND_TIMEOUT=300s

Gunicorn Settings

GUNICORN_TIMEOUT_S

Type: Integer
Default: 300 Maximum seconds a worker can handle a request before being killed.

GUNICORN_TIMEOUT_S=300

GUNICORN_MAX_REQUESTS

Type: Integer
Default: 300 Maximum requests a worker processes before restarting (prevents memory leaks).

GUNICORN_MAX_REQUESTS=300

GUNICORN_WORKERS

Type: Integer
Default: 3 Number of worker processes.

GUNICORN_WORKERS=3

GUNICORN_THREADS

Type: Integer
Default: 3 Number of threads per worker.

GUNICORN_THREADS=3

Email Settings

EMAIL_HOST

Type: String
Default: smtp4dev SMTP server hostname.

# Development
EMAIL_HOST=smtp4dev

# Production
EMAIL_HOST=smtp.yourprovider.com

EMAIL_PORT

Type: Integer
Default: 25 SMTP server port.

EMAIL_PORT=587  # TLS
# or
EMAIL_PORT=465  # SSL

EMAIL_USE_TLS

Type: Boolean
Default: False Use TLS encryption.

EMAIL_USE_TLS=True

EMAIL_USE_SSL

Type: Boolean
Default: False Use SSL encryption.

EMAIL_USE_SSL=False

EMAIL_HOST_USER

Type: String
Default: user SMTP authentication username.

EMAIL_HOST_USER=[email protected]

EMAIL_HOST_PASSWORD

Type: String
Default: password SMTP authentication password.

EMAIL_HOST_PASSWORD=your-smtp-password

DEFAULT_FROM_EMAIL

Type: Email
Default: webmaster@localhost Default sender email address.

DEFAULT_FROM_EMAIL=[email protected]

Authentication Settings

QFIELDCLOUD_PASSWORD_LOGIN_IS_ENABLED

Type: Boolean (0 or 1)
Default: 1 Enable/disable password-based login.

QFIELDCLOUD_PASSWORD_LOGIN_IS_ENABLED=1

ACCOUNT_EMAIL_VERIFICATION

Type: String
Default: optional
Options: mandatory, optional, none Email verification requirement level.

# Production
ACCOUNT_EMAIL_VERIFICATION=mandatory

# Development
ACCOUNT_EMAIL_VERIFICATION=optional

QFIELDCLOUD_ACCOUNT_ADAPTER

Type: String
Default: qfieldcloud.core.adapters.AccountAdapterSignUpOpen
Options:

qfieldcloud.core.adapters.AccountAdapterSignUpOpen - Open signup
qfieldcloud.core.adapters.AccountAdapterSignUpClosed - Closed signup

# Open registration
QFIELDCLOUD_ACCOUNT_ADAPTER=qfieldcloud.core.adapters.AccountAdapterSignUpOpen

# Closed registration (invite-only)
QFIELDCLOUD_ACCOUNT_ADAPTER=qfieldcloud.core.adapters.AccountAdapterSignUpClosed

QFIELDCLOUD_AUTH_TOKEN_EXPIRATION_HOURS

Type: Integer
Default: 720 (30 days) Authentication token expiration time in hours.

QFIELDCLOUD_AUTH_TOKEN_EXPIRATION_HOURS=720

SOCIALACCOUNT_PROVIDERS

Type: JSON
Default: {} OIDC/OAuth2 provider configurations.

SOCIALACCOUNT_PROVIDERS='{
  "google": {
    "OAUTH_PKCE_ENABLED": true,
    "APP": {
      "client_id": "your-client-id",
      "key": ""
    }
  },
  "github": {
    "APP": {
      "client_id": "your-client-id",
      "secret": "your-client-secret"
    }
  }
}'

Django Settings

DJANGO_ALLOWED_HOSTS

Type: Space-separated string
Default: localhost 127.0.0.1 0.0.0.0 app nginx Allowed hostnames for Django. Must include your domain.

DJANGO_ALLOWED_HOSTS="yourcompany.com localhost 127.0.0.1 app nginx"

DJANGO_SETTINGS_MODULE

Type: String
Default: qfieldcloud.settings Django settings module to use.

DJANGO_SETTINGS_MODULE=qfieldcloud.settings

Worker Settings

QFIELDCLOUD_WORKER_QFIELDCLOUD_URL

Type: URL
Default: http://app:8000/api/v1/ QFieldCloud API URL used by workers.

QFIELDCLOUD_WORKER_QFIELDCLOUD_URL=http://app:8000/api/v1/

QFIELDCLOUD_WORKER_REPLICAS

Type: Integer
Default: 1 Number of parallel worker instances.

QFIELDCLOUD_WORKER_REPLICAS=3

TMP_DIRECTORY

Type: Absolute Path
Default: /tmp Directory for temporary files shared between containers.

TMP_DIRECTORY=/tmp

Docker Settings

COMPOSE_PROJECT_NAME

Type: String
Default: qfieldcloud Prefix for Docker containers.

COMPOSE_PROJECT_NAME=qfieldcloud

COMPOSE_FILE

Type: Colon-separated list
Default: docker-compose.yml:docker-compose.override.local.yml Docker Compose files to use.

# Production
COMPOSE_FILE=docker-compose.yml

# Standalone
COMPOSE_FILE=docker-compose.yml:docker-compose.override.standalone.yml

# Local development
COMPOSE_FILE=docker-compose.yml:docker-compose.override.local.yml:docker-compose.override.standalone.yml

Standalone-Only Settings

These settings only apply when using docker-compose.override.standalone.yml.

MinIO Settings

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
MINIO_API_PORT=8009
MINIO_BROWSER_PORT=8010

PostgreSQL Settings

POSTGIS_IMAGE_VERSION=17-3.5-alpine
HOST_POSTGRES_PORT=5433

SMTP4Dev Settings

SMTP4DEV_WEB_PORT=8012
SMTP4DEV_SMTP_PORT=25
SMTP4DEV_IMAP_PORT=143

Monitoring Settings

SENTRY_DSN

Type: String
Default: (empty) Sentry DSN for error tracking. Leave empty to disable.

SENTRY_DSN=https://[email protected]/project-id

SENTRY_SAMPLE_RATE

Type: Float (0-1)
Default: 1 Sentry sample rate.

SENTRY_SAMPLE_RATE=1

SENTRY_RELEASE

Type: String
Default: dev Release version shown in Sentry.

SENTRY_RELEASE=v1.2.3

Configuration Examples

Minimal Production Configuration

# General
DEBUG=0
ENVIRONMENT=production
QFIELDCLOUD_HOST=qfield.yourcompany.com

# Security
SECRET_KEY=<generate-long-random-string>
SALT_KEY=<generate-long-random-string>

# Database (external)
POSTGRES_USER=qfieldcloud
POSTGRES_PASSWORD=<strong-password>
POSTGRES_DB=qfieldcloud_db
POSTGRES_HOST=postgres.yourcompany.com
POSTGRES_PORT=5432
POSTGRES_SSLMODE=require

# Storage (AWS S3)
STORAGES='{...S3 config...}'

# TLS
QFIELDCLOUD_TLS_CERT="/etc/letsencrypt/live/${QFIELDCLOUD_HOST}/fullchain.pem"
QFIELDCLOUD_TLS_KEY="/etc/letsencrypt/live/${QFIELDCLOUD_HOST}/privkey.pem"

# Email
EMAIL_HOST=smtp.sendgrid.net
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=apikey
EMAIL_HOST_PASSWORD=<your-sendgrid-api-key>
DEFAULT_FROM_EMAIL=[email protected]

# Authentication
ACCOUNT_EMAIL_VERIFICATION=mandatory

# Django
DJANGO_ALLOWED_HOSTS="qfield.yourcompany.com app nginx"

# Docker
COMPOSE_FILE=docker-compose.yml

Next Steps

After configuring your environment:

Review SSL Certificate Setup
Configure Database and Storage
Set up monitoring and backups
Test your configuration thoroughly

Get Started

Core Features

Team Management

Deployment

Development

​Overview

​General Settings

​DEBUG

​QFIELDCLOUD_HOST

​ENVIRONMENT

​Security Settings

​SECRET_KEY

​SALT_KEY

​Certificate Settings

​QFIELDCLOUD_TLS_CERT

​QFIELDCLOUD_TLS_KEY

​QFIELDCLOUD_TLS_DHPARAMS

​Let’s Encrypt Settings

​LETSENCRYPT_EMAIL

​LETSENCRYPT_RSA_KEY_SIZE

​LETSENCRYPT_STAGING

​Database Settings

​POSTGRES_USER

​POSTGRES_PASSWORD

​POSTGRES_DB

​POSTGRES_HOST

​POSTGRES_PORT

​POSTGRES_SSLMODE

​Storage Settings

​STORAGES

​Default S3/MinIO Configuration

​AWS S3 Configuration

​WebDAV Configuration

​STORAGES_PROJECT_DEFAULT_STORAGE

​STORAGES_PROJECT_DEFAULT_ATTACHMENTS_STORAGE

​Nginx Settings

​WEB_HTTP_PORT

​WEB_HTTPS_PORT

​NGINX_ERROR_LOG_LEVEL

​NGINX_CLIENT_MAX_BODY_SIZE

​NGINX_PROXY_TIMEOUTS

​Gunicorn Settings

​GUNICORN_TIMEOUT_S

​GUNICORN_MAX_REQUESTS

​GUNICORN_WORKERS

​GUNICORN_THREADS

​Email Settings

​EMAIL_HOST

​EMAIL_PORT

​EMAIL_USE_TLS

​EMAIL_USE_SSL

​EMAIL_HOST_USER

​EMAIL_HOST_PASSWORD

​DEFAULT_FROM_EMAIL

​Authentication Settings

​QFIELDCLOUD_PASSWORD_LOGIN_IS_ENABLED

​ACCOUNT_EMAIL_VERIFICATION

​QFIELDCLOUD_ACCOUNT_ADAPTER

​QFIELDCLOUD_AUTH_TOKEN_EXPIRATION_HOURS

​SOCIALACCOUNT_PROVIDERS

​Django Settings

​DJANGO_ALLOWED_HOSTS

​DJANGO_SETTINGS_MODULE

​Worker Settings

​QFIELDCLOUD_WORKER_QFIELDCLOUD_URL

​QFIELDCLOUD_WORKER_REPLICAS

​TMP_DIRECTORY

​Docker Settings

​COMPOSE_PROJECT_NAME

​COMPOSE_FILE

​Standalone-Only Settings

​MinIO Settings

​PostgreSQL Settings

​SMTP4Dev Settings

​Monitoring Settings

​SENTRY_DSN

​SENTRY_SAMPLE_RATE

​SENTRY_RELEASE

​Configuration Examples

​Minimal Production Configuration

Overview

General Settings

DEBUG

QFIELDCLOUD_HOST

ENVIRONMENT

Security Settings

SECRET_KEY

SALT_KEY

Certificate Settings

QFIELDCLOUD_TLS_CERT

QFIELDCLOUD_TLS_KEY

QFIELDCLOUD_TLS_DHPARAMS

Let’s Encrypt Settings

LETSENCRYPT_EMAIL

LETSENCRYPT_RSA_KEY_SIZE

LETSENCRYPT_STAGING

Database Settings

POSTGRES_USER

POSTGRES_PASSWORD

POSTGRES_DB

POSTGRES_HOST

POSTGRES_PORT

POSTGRES_SSLMODE

Storage Settings

STORAGES

Default S3/MinIO Configuration

AWS S3 Configuration

WebDAV Configuration

STORAGES_PROJECT_DEFAULT_STORAGE

STORAGES_PROJECT_DEFAULT_ATTACHMENTS_STORAGE

Nginx Settings

WEB_HTTP_PORT

WEB_HTTPS_PORT

NGINX_ERROR_LOG_LEVEL

NGINX_CLIENT_MAX_BODY_SIZE

NGINX_PROXY_TIMEOUTS

Gunicorn Settings

GUNICORN_TIMEOUT_S

GUNICORN_MAX_REQUESTS

GUNICORN_WORKERS

GUNICORN_THREADS

Email Settings

EMAIL_HOST

EMAIL_PORT

EMAIL_USE_TLS

EMAIL_USE_SSL

EMAIL_HOST_USER

EMAIL_HOST_PASSWORD

DEFAULT_FROM_EMAIL

Authentication Settings

QFIELDCLOUD_PASSWORD_LOGIN_IS_ENABLED

ACCOUNT_EMAIL_VERIFICATION

QFIELDCLOUD_ACCOUNT_ADAPTER

QFIELDCLOUD_AUTH_TOKEN_EXPIRATION_HOURS

SOCIALACCOUNT_PROVIDERS

Django Settings

DJANGO_ALLOWED_HOSTS

DJANGO_SETTINGS_MODULE

Worker Settings

QFIELDCLOUD_WORKER_QFIELDCLOUD_URL

QFIELDCLOUD_WORKER_REPLICAS

TMP_DIRECTORY

Docker Settings

COMPOSE_PROJECT_NAME

COMPOSE_FILE

Standalone-Only Settings

MinIO Settings

PostgreSQL Settings

SMTP4Dev Settings

Monitoring Settings

SENTRY_DSN

SENTRY_SAMPLE_RATE

SENTRY_RELEASE

Configuration Examples

Minimal Production Configuration

Next Steps