About IPTeller

Server-side visitor and IP analytics.

IPTeller is a Django/PostgreSQL visitor analytics platform that uses Celery and Redis for asynchronous processing and GeoIP services to enrich public IP addresses with geographic and network intelligence.

How it works

Django middleware captures incoming requests and records visitor identity, IP address, request path, HTTP method, response status, referrer, user-agent, and response time. Visitors use persistent UUID cookies, while IP addresses are stored as unique records associated with individual visits.

Lightweight request recording stays in the HTTP lifecycle. Expensive work, including GeoIP enrichment, runs asynchronously through Celery so the monitored application does not wait for external services.

Asynchronous IP enrichment

When IPTeller sees an unprocessed public IP address, it sends an enrichment job to the dedicated ipteller Celery queue. The worker queries ipwho.is and stores country, city, latitude, longitude, ISP, and ASN data.

A processing flag prevents duplicate enrichment. Private, loopback, reserved, and non-public addresses are excluded from external lookups.

Internal architecture

Django application
        │
        ▼
VisitorMiddleware
        │
        ├── Identify visitor
        ├── Identify IP address
        └── Record visit
                │
                ▼
           PostgreSQL
                │
                │ Unprocessed public IP
                ▼
     Celery: ipteller queue
                │
                ▼
             Redis
                │
                ▼
          Celery worker
                │
                ▼
        GeoIP provider
                │
                ▼
           PostgreSQL
                │
                ▼
         Analytics UI / API

Core technologies

Component	Technology	Purpose
Web framework	Django	Application, middleware, models, HTTP processing
Database	PostgreSQL	Persistent visitor, IP, and visit data
Task processing	Celery	Asynchronous and background processing
Message broker	Redis DB 0	Celery task queue transport
Task results	Redis DB 2	Ipteller Celery results
Scheduling	Celery Beat	Periodic retention and maintenance tasks
GeoIP	ipwho.is	Geographic and network enrichment
Web server	Gunicorn	Django application serving
Reverse proxy	Nginx	HTTPS termination and proxying
Runtime	Python 3.12	Application runtime

Designed as a reusable Django application

IPTeller can run as a standalone analytics service or as a reusable analytics application inside an existing Django project. Install the app, add its middleware, configure PostgreSQL, Redis, and Celery, and the host project begins collecting and enriching visitor data.

The UI or a future REST API can expose traffic history, IP intelligence, geographic distributions, referrers, response-time statistics, bot detection, anomaly detection, and threat-intelligence signals.

Security and operations

Manual enforcement: a Blocked status in Suspics is a review status and does not automatically block requests.
Review actions: staff can review, allowlist, or temporarily block suspicious IP addresses.
Threshold tuning: detection rules are reviewed over time to reduce false positives.
Testing: middleware collection and risk-scoring rules should be tested before changes are deployed.
Service monitoring: Celery Beat and workers run scheduled cleanup and risk analysis.
Retention and access: analytics data is retained according to the configured policy and restricted to authorized staff.

Operational notes

Public signup: new accounts are not staff and cannot access dashboards. Internal deployments may remove public signup entirely.
IP privacy: IP addresses, user agents, and referrers can be personal data. Restrict access and document retention.
Blocked is not enforcement: Suspics status records a decision only until explicit Nginx or Django enforcement is added.
Trust boundary: Gunicorn uses a Unix socket and trusts Nginx forwarding headers. Keep the socket inaccessible to untrusted local users.
Backups: back up PostgreSQL and test restoration before relying on long-term retention.
Monitoring: monitor Celery Beat, workers, task retries, database growth, and unexpected 4xx or 5xx increases.
Tests: test visit capture, GeoIP exclusions, retention cleanup, and Suspics scoring before tuning or enforcing scores.

Protection measures

For real protection, consider adding:

Nginx rate limits and request-size limits.
Fail2ban or firewall rules for confirmed abusive IP addresses.
Django login throttling and strong admin access controls.
A WAF or CDN for public-facing attacks.
Manual review before blocking, using Suspics as evidence.