Prerequisites
Before you begin, ensure you have:
- Docker Engine 20.10 or later installed
- Docker Compose 2.0 or later installed
- A server with at least 4 GB RAM (8 GB recommended)
- A public domain name pointing to your server (for SSL certificates)
- Basic knowledge of Docker and command line operations
Clone the Repository
First, clone the QFieldCloud repository with all its submodules:
git clone --recurse-submodules [email protected]:opengisch/QFieldCloud.git
cd QFieldCloud
git pull --recurse-submodules && git submodule update --recursive
Initial Configuration
1. Create Environment File
Copy the example environment file and edit it:
cp .env.example .env
vi .env
You must change these values before deploying to production!
.env file and update at minimum:
# Disable debug mode for production
DEBUG=0
# Set your domain name
QFIELDCLOUD_HOST=your-domain.com
# Generate a strong secret key (e.g., using: pwgen -sn 128)
SECRET_KEY=your-very-long-random-secret-key-here
# Generate a salt key (e.g., using: pwgen -sn 128)
SALT_KEY=your-very-long-random-salt-key-here
# Set a strong database password (e.g., using: pwgen -sn 16)
POSTGRES_PASSWORD=your-strong-database-password
# Configure allowed hosts (include your domain)
DJANGO_ALLOWED_HOSTS="your-domain.com localhost 127.0.0.1 app nginx"
# Set email verification to mandatory for production
ACCOUNT_EMAIL_VERIFICATION=mandatory
COMPOSE_FILE variable in your .env:
# For production with external database and S3
COMPOSE_FILE=docker-compose.yml
# For standalone deployment (NOT recommended for production)
COMPOSE_FILE=docker-compose.yml:docker-compose.override.standalone.yml
The standalone configuration includes PostgreSQL, MinIO, and SMTP services in docker-compose. This is not recommended for production and is entirely at your own risk.
Build and Start Services
1. Build and Run Containers
Build the Docker images and start all services:
docker compose up -d --build
- Build custom Docker images for the application
- Pull required base images
- Start all services defined in your compose configuration
- Run services in detached mode
2. Run Database Migrations
Initialize the database schema:
docker compose exec app python manage.py migrate
3. Collect Static Files
Gather all static assets (CSS, JavaScript, images):
docker compose exec app python manage.py collectstatic --noinput
4. Create Superuser Account
Create an admin user to access the Django admin interface:
docker compose run app python manage.py createsuperuser --username admin --email [email protected]
Verify Installation
Check Service Health
Verify that QFieldCloud is running correctly:
curl https://your-domain.com/api/v1/status/
database and storage keys showing ok status:
{
"database": "ok",
"storage": "ok"
}
Check Service Logs
If there are issues, check the logs:
# View all logs
docker compose logs
# View specific service logs
docker compose logs nginx app
# Follow logs in real-time
docker compose logs -f nginx app
Enhanced Nginx Logs
For detailed nginx request logs with timing information:
QFC_JQ='[.ts, .ip, (.method + " " + (.status|tostring) + " " + (.resp_time|tostring) + "s"), .uri, "I " + (.request_length|tostring) + " O " + (.resp_body_size|tostring), "C " + (.upstream_connect_time|tostring) + "s", "H " + (.upstream_header_time|tostring) + "s", "R " + (.upstream_response_time|tostring) + "s", .user_agent] | @tsv'
docker compose logs nginx -f --no-log-prefix | grep ':"nginx"' | jq -r $QFC_JQ
Accessing Services
Once deployed, you can access:
- QFieldCloud Web Interface:
https://your-domain.com
- Django Admin:
https://your-domain.com/admin/
- API Documentation:
https://your-domain.com/swagger/
- API Status:
https://your-domain.com/api/v1/status/
Standalone Services (Development/Testing)
If using the standalone configuration, additional services are available:
- MinIO Browser:
http://your-domain.com:8010
- SMTP4Dev Web Interface:
http://your-domain.com:8012
Database Access
For standalone deployments with local PostgreSQL:
Direct Container Access
docker compose exec -it db psql -U qfieldcloud_db_admin -d qfieldcloud_db
Using pg_service.conf
Create or edit ~/.pg_service.conf:
[localhost.qfield.cloud]
host=localhost
dbname=qfieldcloud_db
user=qfieldcloud_db_admin
port=5433
password=your-database-password
sslmode=disable
psql 'service=localhost.qfield.cloud'
Managing Services
Stop Services
Start Services
Restart Services
Stop and Remove Containers
View Running Containers
Updating QFieldCloud
1. Pull Latest Changes
git pull --recurse-submodules && git submodule update --recursive
2. Rebuild Containers
docker compose up -d --build
3. Run Migrations
docker compose exec app python manage.py migrate
4. Collect Static Files
docker compose exec app python manage.py collectstatic --noinput
Compiling Translations (Optional)
If your instance needs to support multiple languages:
docker compose run --user root app python manage.py compilemessages
Troubleshooting
Services Won’t Start
-
Check if ports are already in use:
sudo netstat -tlnp | grep -E ':(80|443|5433)'
-
Check Docker logs:
Database Connection Errors
-
Verify database is running:
-
Check database logs:
-
Verify credentials in
.env file
Storage Issues
- Check storage service health endpoint
- Verify MinIO/S3 credentials in
.env
- Check storage service logs:
docker compose logs minio
Permission Issues
-
Ensure proper file permissions:
sudo chown -R 1000:1000 .
-
Check volume permissions:
docker compose exec app ls -la /usr/src/app
Next Steps
After successfully deploying QFieldCloud:
- Configure SSL Certificates for HTTPS
- Review Environment Configuration for advanced settings
- Set up Database Backups
- Configure monitoring and alerting
- Review security best practices
Production Recommendations
Before going to production:
- Use external managed PostgreSQL database
- Use external S3-compatible storage with versioning
- Configure automatic backups
- Set up monitoring and alerts
- Use Let’s Encrypt for SSL certificates
- Configure email verification as mandatory
- Set up log aggregation
- Configure resource limits in docker-compose
- Test disaster recovery procedures
