Privacy-first mobile analytics server. Self-hosted, session-based, 5-field storage.
No personal data retained.

Quick Start • API Reference • SDKs • Configuration • Contributing

Respectlytics helps developers avoid collecting personal data in the first place. Our motto is Return of Avoidance (ROA) — we believe the best way to handle sensitive data is to never collect it.

We use anonymized identifiers stored only in device memory (RAM) that rotate automatically every two hours or upon app restart. IP addresses are processed transiently for approximate country lookup and immediately discarded — no personal data is ever persisted.

Only 5 fields are stored per event:

Our system is transparent about exactly what data is collected, defensible because we minimize data by design, and clear about why each field exists. Consult your legal team to determine your specific requirements.

Get a running instance in under 2 minutes:

# 1. Clone the repository
git clone https://github.com/respectlytics/respectlytics.git
cd respectlytics

# 2. Copy environment file
cp .env.example .env

# 3. Generate a secret key
python3 -c "from secrets import token_urlsafe; print(f'SECRET_KEY={token_urlsafe(50)}')" >> .env

# 4. Start the services
docker compose up -d

# 5. Create your admin account
docker compose exec web python manage.py createsuperuser

Open http://localhost:8080 — you're ready to go.

• Python 3.12+
• PostgreSQL 14+ (required — SQLite is not supported)
• Node.js 18+ (only for Tailwind CSS development)

# Clone and enter
git clone https://github.com/respectlytics/respectlytics.git
cd respectlytics

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL and SECRET_KEY at minimum

# Run migrations
python manage.py migrate

# Create admin user
python manage.py createsuperuser

# Collect static files
python manage.py collectstatic --noinput

# Start the server
gunicorn core.wsgi:application --bind 0.0.0.0:8080 --workers 2 --threads 3

Important: PostgreSQL is required. We use django.contrib.postgres aggregates (e.g., ArrayAgg) that are not available in SQLite.

All configuration is via environment variables. See .env.example for the complete list.

Production: Always set SECRET_KEY to a random string, DEBUG=False, and ALLOWED_HOSTS to your domain. If running behind an HTTPS reverse proxy (nginx, Caddy), also set SECURE_SSL=True. If using managed PostgreSQL (AWS RDS, DigitalOcean), also set DATABASE_SSL=True.

Country detection is optional but recommended. It uses the free MaxMind GeoLite2 database.

1. Create a free account at maxmind.com/en/geolite2/signup
2. Generate a license key in your MaxMind account
3. Set the environment variables:

   MAXMIND_ACCOUNT_ID=your_account_id
   MAXMIND_LICENSE_KEY=your_license_key

4. Download the database:

   python manage.py update_geoip

With Docker, the GeoIP database is downloaded automatically on container startup when credentials are provided.

Without GeoIP, events will have country=null — everything else works normally.

The built-in API reference is available at /api/v1/reference/ when the server is running.

SDK / API endpoints use app key authentication via the X-App-Key header:

curl -X POST https://your-server.com/api/v1/events/ \
  -H "Content-Type: application/json" \
  -H "X-App-Key: your-app-key-here" \
  -d '{"event_name": "app_opened", "session_id": "abc123", "platform": "ios"}'

Dashboard uses session-based authentication (login via browser).

For detailed API documentation, see docs/REFERENCE.md.

Official SDKs for mobile platforms:

configure(appKey, serverUrl)  — Initialize the SDK
track(eventName)              — Track an analytics event
flush()                       — Force send queued events

# Preview what would be deleted (no changes made)
python manage.py purge_old_events --dry-run

# Delete events older than 730 days (default)
python manage.py purge_old_events

# Delete events older than 365 days
python manage.py purge_old_events --days 365

# Run weekly on Sunday at 3 AM
0 3 * * 0 cd /app && python manage.py purge_old_events >> /var/log/respectlytics/purge.log 2>&1

docker compose exec web python manage.py purge_old_events