Skip to main content
This guide walks you through setting up a local development environment for QFieldCloud.

​
Prerequisites

  • Git
  • Docker and Docker Compose
  • Python 3.10+
  • (Optional) pre-commit for code quality hooks

​
Clone the Repository

Clone the repository with all submodules: 
git clone --recurse-submodules [email protected]:opengisch/QFieldCloud.git
cd QFieldCloud
To fetch upstream development later, update submodules: 
git pull --recurse-submodules && git submodule update --recursive

​
Configure Environment

  1. Copy the example environment file:
cp .env.example .env
  1. (Optional) Customize the .env file for your local setup. Key variables for development:
DEBUG=1
ENVIRONMENT=development
COMPOSE_FILE=docker-compose.yml:docker-compose.override.local.yml:docker-compose.override.standalone.yml
QFIELDCLOUD_HOST=localhost
DJANGO_ALLOWED_HOSTS="localhost 127.0.0.1 0.0.0.0 app nginx"

​
Build and Start Services

Build the development images and start all containers: 
docker compose up -d --build
The stack includes:
  • app: Django application (accessible at http://localhost:8011 directly, or https://localhost via nginx)
  • nginx: Reverse proxy with SSL
  • db: PostgreSQL/PostGIS database
  • minio: S3-compatible object storage
  • worker_wrapper: Background job processor
  • smtp4dev: Email testing tool (web UI at http://localhost:8012)
Always develop and test through the nginx reverse proxy at https://localhost rather than using the Django built-in server directly.

​
Initialize the Database

  1. Run Django database migrations:
docker compose exec app python manage.py migrate
  1. Collect static files (CSS, JS, etc.):
docker compose run app python manage.py collectstatic --noinput
  1. Create a superuser for accessing the Django admin:
docker compose run app python manage.py createsuperuser --username super_user --email [email protected]

​
(Optional) Load Sample Data

If you have a database dump for development: 
psql 'service=localhost.qfield.cloud' < ./qfc_dump_20220304.sql

​
Trust the SSL Certificate

QFieldCloud automatically generates a self-signed certificate in ./conf/nginx/certs. To avoid SSL errors, trust the root certificate.

​
On Debian/Ubuntu

Copy and trust the certificate: 
sudo cp ./conf/nginx/certs/rootCA.pem /usr/local/share/ca-certificates/rootCA.crt
sudo update-ca-certificates
Verify it works: 
curl https://localhost/api/v1/status/

​
Remove the Certificate

To remove the trusted certificate: 
sudo rm /usr/local/share/ca-certificates/rootCA.crt
sudo update-ca-certificates --fresh

​
Access the Application

After setup:

​
Verify Installation

Check the health status: 
curl https://localhost/api/v1/status/
Expect a JSON response with "database": "ok" and "storage": "ok".

​
Database Access

Connect to the PostgreSQL database:

​
Via Docker

docker compose exec -it db psql -U qfieldcloud_db_admin -d qfieldcloud_db

​
Via pg_service.conf

Create ~/.pg_service.conf: 
[localhost.qfield.cloud]
host=localhost
dbname=qfieldcloud_db
user=qfieldcloud_db_admin
port=5433
password=3shJDd2r7Twwkehb
sslmode=disable

[test.localhost.qfield.cloud]
host=localhost
dbname=test_qfieldcloud_db
user=qfieldcloud_db_admin
port=5433
password=3shJDd2r7Twwkehb
sslmode=disable
Then connect: 
psql 'service=localhost.qfield.cloud'

​
Compile Translations

If working on translations: 
docker compose run --user root app python manage.py compilemessages

​
Managing Dependencies

QFieldCloud uses pip-compile to manage Python dependencies. To regenerate all requirements*.txt files: 
docker compose run --rm pipcompile
To compile a single requirements file: 
docker compose run --rm pipcompile pip-compile --no-strip-extras -o requirements/requirements_worker_wrapper.txt requirements/requirements_worker_wrapper.in

​
Troubleshooting

​
Check Logs

View logs for specific services: 
docker compose logs nginx app
docker compose logs -f worker_wrapper  # Follow logs

​
Check Service Status

docker compose ps

​
Rebuild Services

If you’ve made changes to Dockerfile or dependencies: 
docker compose up -d --build

​
Reset the Database

To start fresh: 
docker compose down -v  # Removes volumes
docker compose up -d --build
docker compose exec app python manage.py migrate
docker compose run app python manage.py createsuperuser

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us