Configuration

Warning

🚧 Work in progress

This section is partly outdated and currently under active development and may change without notice. Content, examples, and screenshots may be incomplete or updated soon.

You can override many default settings in TRAPPER by adjusting the environmental variables listed in the file .env. Further in this section we provide some examples of how to customize selected aspects of TRAPPER.

Basic settings

Provide a name of your TRAPPER instance domain:

DOMAIN_NAME=demo.trapper-project.org

The SECRET_KEY is used to provide cryptographic signing, and should be set to a unique, unpredictable value (see django docs):

SECRET_KEY='cudv86xkzva)o1lkt-ow72)y__*xwsb1@43wtp1cc@zak=i@@e'

Define users that are admins and managers of your TRAPPER instance. If the Email service is properly configured, admins will be notified about all server errors (500) and managers will be sent notifications about new user registrations and requests for approving new research projects. You can add 2 admins and 2 managers by providing username and email as shown below.

ADMIN1=admin1,admin1@oscf.org # {username},{email}
ADMIN2=admin2,admin2@oscf.org

MANAGER1=manager1,manager1@oscf.org
MANAGER2=manager2,manager2@oscf.org

HTTP & HTTPS ports mapping definition is used to configure the trapper-nginx docker container (see nginx docker docs):

HTTP_PORTS=80:80
HTTPS_PORTS=443:443

SSL certificates

If you already have the SSL certificates for your TRAPPER website you can use them by setting the following variables:

# default configuration
SSL_CERTIFICATE=${PWD}/ssl/cert.pem
SSL_CERTIFICATE_KEY=${PWD}/ssl/key.pem

The example with the Let’s Encrypt certificates:

SSL_CERTIFICATE=/etc/letsencrypt/live/trapper/fullchain.pem
SSL_CERTIFICATE_KEY=/etc/letsencrypt/live/trapper/privkey.pem

These certificates will be used to configure the HTTPS nginx proxy-server within a dedicated container (see trapper-nginx) and to secure the FTP connections (TLS) to the pure-ftpd docker container.

Note

When there is no SSL certificates provided they will be generated automatically using the openssl toolkit (self-signed certificates).

Using an external database

TRAPPER comes with a pre-configured postgresql docker image (see trapper-posgresql) and has been proved to work well with the recent postgresql-12 and postgis-3.0. The basic credentials needed to access this dockerized postgresql database volume can be configured with these parameters:

POSTGRES_USER=trapper
POSTGRES_PASSWORD=trapper
POSTGRES_DB=trapper

However, for a production-grade TRAPPER instance we recommend to configure an external postgresql database either running on the same virtual machine or on different remote server. In the .env file there are the following variables that can be used to configure a connection with an external database:

DB_NAME=trapper
DB_USER=trapper
DB_PASS=trapper
DB_HOST=172.17.0.1
DB_PORT=5432

Note

The host address 172.17.0.1 is for the case when the postgresql database is running on the same machine as TRAPPER docker container. This host ip should work for most of the standard Linux distributions, including the recent Ubuntu Server LTS 20.04.

Now you can run TRAPPER using the script start.sh and the extra flag -d:

$ ./start.sh -pbd prod

Note

You will still need to properly configure your external postgresql server which is out of the scope of this documentation. Here we only give you a couple of quick cues to help you make the connection between TRAPPER and postgresql working as expected (but be aware that likely you need more restrictive configuration!):

  1. In the file /etc/postgresql/12/main/postgresql.conf update the following line:

    listen_addresses = '*'

  2. In the file /etc/postgresql/12/main/pg_hba.conf add the following entry:

    # TYPE   DATABASE   USER   ADDRESS       METHOD
host     all        all    172.0.0.0/8   md5

    172.0.0.0/8 matches all ip addresses starting with 172.X.X.X

Storage

The multimedia files uploaded to TRAPPER (i.e. camera trapping images & videos) can be stored either locally, i.e. using a storage infrastructure available at a virtual machine running TRAPPER docker container, or remotely in a cloud storage (see the subsection Cloud storage for details about supported cloud storage providers).

To use a local storage (default option) leave the following parameter empty:

DEFAULT_FILE_STORAGE=

Optionally, you can provide paths to local directories which will be used to mount the corresponding docker volumes:

VOL_MEDIA=/storage/trapper_data/media
VOL_EXTERNAL_MEDIA=/storage/trapper_data/external_media

Note

In a directory mounted as the volume VOL_MEDIA all images & videos uploaded to TRAPPER are stored in the following format:

# original files
protected/storage/resources/{user_id}/{date_uploaded}/

# preview files (for images)
protected/storage/resources/{user_id}/{date_uploaded}/previews/

# thumbnails (for both images & videos)
protected/storage/resources/{user_id}/{date_uploaded}/thumbnails/

The volume VOL_EXTERNAL_MEDIA provides a storage for users’ data including FTP data (e.g. users’ uploaded .zip files with multimedia collections) and all data packages exported from TRAPPER.

Cloud storage

The TRAPPER support for a cloud storage is based on a wonderful django package django-storages. Here is the list of cloud storage providers currently supported by TRAPPER and their corresponding configuration parameters:

  1. Azure

    DEFAULT_FILE_STORAGE=azure

AZURE_ACCOUNT_NAME=trapper
AZURE_ACCOUNT_KEY=key
AZURE_CONTAINER=trapper_data

AZURE_CUSTOM_DOMAIN=trapper.blob.core.windows.net
MEDIA_LOCATION=media

  2. Amazon S3

AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY - credentials for authorizing access to S3 storage.

AWS_STORAGE_BUCKET_NAME - S3 bucket name for storing all media files

AWS_S3_REGION_NAME - Name of AWS S3 region to use. Optional.

AWS_S3_ENDPOINT_URL - S3 Endpoint, required in order to use alternative S3-compatible storages such as Minio or Backblaze B2

Setting default file storage as amazon_s3 is required in order to use S3 integration in TRAPPER

DEFAULT_FILE_STORAGE=amazon_s3

Email service

The working email service is required to make the notification framework working correctly. This feature is turned off by default. To configure the email notification backend you should set the following parameters (example with gmail):

EMAIL_NOTIFICATIONS=True
EMAIL_NOTIFICATIONS_RESEARCH_PROJECT=True
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=project@gmail.com
EMAIL_HOST_PASSWORD=password
EMAIL_USE_TLS=True

Note

If local SMTP server is used it has to be configured to be able to send email messages. Configuration of the SMTP server is out of the scope of this documentation.

Users registration

Here you can define if users registration (signing-up) is open or not and optionally secure a user registration form with Google’s recaptcha authentication.

USER_REGISTRATION_OPEN=True

# Google recaptcha settings
USE_RECAPTCHA=True
RECAPTCHA_PUBLIC_KEY=public_key
RECAPTCHA_PRIVATE_KEY=private_key

Django Debug Toolbar

If you are a developer of TRAPPER you can turn on a very cool tool for debugging called Django Debug Toolbar:

USE_DEBUG_TOOLBAR=True
DEBUG_TOOLBAR_USERS=admin1,admin2

AI Pipeline Configuration

TRAPPER features a sophisticated automatic AI pipeline that processes uploaded camera trap images through multiple stages of machine learning analysis. The AI pipeline is configured primarily through Classification Project settings in the Django admin interface, rather than environment variables.

Pipeline Architecture

The AI pipeline consists of four sequential stages:

  1. Object Detection: Identify and locate animals, humans, and vehicles in images

  2. Species Classification: Classify detected animals to species level

  3. Sequence Building: Group related images into meaningful temporal sequences

  4. Privacy Blurring: Automatically blur human faces and vehicle license plates

Configuration is managed through the Classification Project model in the admin interface.

See also

For detailed AI Provider setup instructions, see Administration → AI Provider and Classification Project Configuration.

Classification Project AI Settings

AI pipeline behavior is configured through Classification Project settings in the Django admin interface:

Object Detection and Species Classification

Configure AI models for your Classification Project:

  • Object Detection AI Model: Select TrapperAIProvider with MegaDetector (v5 or v6 variants)

  • Species AI Model: Select TrapperAIProvider with species classifier (e.g., DeepFaune v1.3)

  • Copy AI Classifications: Copy AI results to user classifications for review

  • Required AI: Require AI classification before human annotation

Confidence and Quality Control

Set confidence thresholds and quality control parameters:

  • Species Matching IOU Threshold: Overlap threshold for matching species predictions (default: 0.5)

  • Observation Type Confidence Warning Threshold: Warn when object detection confidence is low

  • Species Confidence Warning Threshold: Warn when species classification confidence is low

Privacy and Blurring Options

Configure automatic privacy protection:

  • Blur Humans: Automatically blur detected human faces

  • Blur Vehicles: Automatically blur detected vehicles and license plates

  • Blur Backup: Keep backup copies of original images before blurring

  • Blur Humans and Vehicles Immediately: Apply blurring immediately after classification

Video Processing

Configure video-specific settings:

  • Video Support Enabled: Enable video processing for the project

  • Target FPS: Set target frame rate for video processing (optional)

Deployment Upload Options

Large Dataset Uploads (trapper-tools)

For large-scale deployments with thousands of images:

# Install trapper-tools
pip install trapper-tools

# Configure connection
trapper-tools configure --url https://your-trapper-instance.org

# Process and upload with AI pipeline
trapper-tools pipeline --data-path /path/to/data --convert --trigger

Single Deployment Uploads (trapper-frontend)

For smaller deployments or user-friendly uploads:

  • Use the web-based upload interface in trapper-frontend

  • Drag-and-drop image uploads with automatic AI processing

  • Real-time progress tracking and results preview

  • Suitable for citizen science projects and smaller datasets

  • Real-time progress tracking and results preview

  • Suitable for citizen science projects and smaller datasets

General Environment Settings

While AI pipeline configuration is primarily managed through the admin interface, some general system settings can be configured via environment variables:

Basic System Settings

# Django settings for AI processing
DJANGO_SETTINGS_MODULE=trapper.settings.production

# Celery configuration for background AI tasks
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# File storage for AI processing
MEDIA_ROOT=/storage/media
STATIC_ROOT=/storage/static

Note

AI pipeline configuration requires careful tuning based on your specific use case, available computational resources, and quality requirements. Start with conservative settings and adjust based on performance monitoring results.

Warning

Enabling AI processing will increase computational and storage requirements. Ensure adequate resources are available and monitor system performance regularly.