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 and Docker Compose installed
  • check_circle Minimum 4GB RAM (8GB+ recommended)
02

Choose Installation Method

03

Repository Setup

No need to clone the full repository. Download the compose file and environment template directly.

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/app/docker-compose.prod.yml
curl -o .env https://raw.githubusercontent.com/Trawlr/App/main/app/.env.example
Command Line Interface terminal
# Clone the repository
git clone https://github.com/Trawlr/App.git
cd trawlr/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
DEBUG=False
SECRET_KEY=<CHANGEME>
SECURE_SSL_REDIRECT=False

DJANGO_SETTINGS_MODULE=trawlr.settings
DJANGO_ALLOW_ASYNC_UNSAFE=true

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

RABBITMQ_HOST=rabbitmq
RABBITMQ_DEFAULT_USER=<CHANGEME>
RABBITMQ_DEFAULT_PASS=<CHANGEME>
RABBITMQ_URL=amqp://<CHANGEME_USERNAME>:<CHANGEME_PASSWORD>@rabbitmq:5672//

TRAWLR_STORAGE_ROOT=/data/trawlr
ALLOWED_HOSTS=localhost,127.0.0.1,<YOUR_DOMAIN>,<YOUR_IP>
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
listener Real-time Telegram connection & message capture
scheduler Periodic task scheduling (APScheduler)
db PostgreSQL 18 database
rabbitmq Message broker for task queues
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
listener Real-time Telegram connection & message capture
scheduler Periodic task scheduling (APScheduler)
db PostgreSQL 18 database
rabbitmq Message broker for task queues
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 subscriptions
  • 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.