Deploy Trawlr.

A tactical guide to setting up your first Trawlr instance.

01

Prerequisites

You must get your user API credentials from the Telegram portal.

  • check_circle Valid api_id and api_hash from my.telegram.org
  • check_circle Docker 24+ and Docker Compose v2
  • check_circle Minimum 8GB RAM (16GB+ recommended)
02

Choose Installation Method

03

Repository Setup

No need to clone the full repository. Download the compose file and environment template directly. The nginx config is embedded inside docker-compose.prod.yml.

Command Line Interface terminal
# Create project directory
mkdir trawlr && cd trawlr

# Download compose file and environment template
curl -O https://raw.githubusercontent.com/Trawlr/App/main/docker-compose.prod.yml
curl -o .env https://raw.githubusercontent.com/Trawlr/App/main/.env.example
Command Line Interface terminal
# Clone the repository
git clone https://github.com/Trawlr/App.git
cd App

# Copy environment template
cp .env.example .env
04

Environment Configuration

Edit the .env file and replace all <CHANGEME> placeholder values.

Environment Variables .env.example
# =============================================================================
# Django
# =============================================================================
DEBUG=False    # NEVER set to True in production
SECRET_KEY=<CHANGEME>
SECURE_SSL_REDIRECT=False    # Set to True when serving over HTTPS

# Allowed hostnames/IP addresses (comma-separated)
ALLOWED_HOSTS=localhost,127.0.0.1

# =============================================================================
# PostgreSQL
# =============================================================================
POSTGRES_DB=trawlr
POSTGRES_USER=trawlr
POSTGRES_PASSWORD=<CHANGEME>
POSTGRES_HOST=db
POSTGRES_PORT=5432

# =============================================================================
# RabbitMQ
# =============================================================================
# These are read by both the RabbitMQ container (to provision the user)
# and by Django (to authenticate against the broker).
RABBITMQ_DEFAULT_USER=<CHANGEME>
RABBITMQ_DEFAULT_PASS=<CHANGEME>
RABBITMQ_HOST=rabbitmq

# AMQP connection URL used by Dramatiq workers and the listener service.
# Use the same username/password as above.
RABBITMQ_URL=amqp://<CHANGEME_USERNAME>:<CHANGEME_PASSWORD>@rabbitmq:5672//

# =============================================================================
# Trawlr Application
# =============================================================================
# Path inside the container where downloaded media is stored.
TRAWLR_STORAGE_ROOT=/data/trawlr

# =============================================================================
# Internals — do not modify
# =============================================================================
DJANGO_SETTINGS_MODULE=trawlr.settings
DJANGO_ALLOW_ASYNC_UNSAFE=true
LISTENER_HEALTH_PORT=8001
05

Deploy

Docker Compose docker-compose.prod.yml
# Pull images and start all services
docker compose -f docker-compose.prod.yml up -d

# Run initial setup (creates admin user & verifies extensions)
docker compose -f docker-compose.prod.yml exec web \
  python manage.py setup \
  --username admin \
  --password your-secure-password

# Verify deployment
docker compose -f docker-compose.prod.yml ps
Service Function
web Django application server (Daphne ASGI)
downloader Download & task processor (gevent pool)
concierge Telegram API tasks (history scans, member scans)
processor Real-time event processor
notifier Delivers entity-notification matches to webhooks & RabbitMQ queues
listener Real-time Telegram connection & message capture
scheduler Periodic task scheduling (APScheduler)
db PostgreSQL 18 database
rabbitmq Message broker for task queues
nginx Media proxy for served files
Docker Compose docker-compose-dev.yml
# Build images and start all services
docker compose -f docker-compose-dev.yml up -d --build

# Run initial setup (creates admin user & verifies extensions)
docker compose -f docker-compose-dev.yml exec web \
  python manage.py setup \
  --username admin \
  --password your-secure-password

# Verify deployment
docker compose -f docker-compose-dev.yml ps
Service Function
web Django application server (Daphne ASGI)
downloader Download & task processor (gevent pool)
concierge Telegram API tasks (history scans, member scans)
processor Real-time event processor
notifier Delivers entity-notification matches to webhooks & RabbitMQ queues
listener Real-time Telegram connection & message capture
scheduler Periodic task scheduling (APScheduler)
db PostgreSQL 18 database
rabbitmq Message broker for task queues
nginx Media proxy for served files
06

Account Registration

Navigate to the web interface at http://localhost:8000 and complete Telegram account linking:

  • arrow_forward Access Accounts section in sidebar
  • arrow_forward Enter phone number with country code
  • arrow_forward Input api_id and api_hash credentials
  • arrow_forward Complete SMS/2FA verification sequence
07

Target Acquisition

Configure channel monitoring and data collection parameters:

  • arrow_forward Use Sync Channels to import existing channels/groups
  • arrow_forward Add targets via username, URL, or invite link
  • arrow_forward Configure auto-download preferences per source
  • arrow_forward Set media type priorities (photos, videos, files)
  • arrow_forward Execute Scan History for retroactive collection
shield

Security Notice

We do NOT recommend exposing Trawlr to the internet. Out of the box integration with Traefik will be available in the v1.1 release. Until then we recommend you put Trawlr behind a suitable reverse proxy.

build

Common Issues

FloodWaitError

API rate limit triggered. System auto-retries after cooldown period.

Session Expired

Re-authenticate via Accounts section after extended inactivity.

Downloads Stalled

Verify worker containers running with docker compose ps.