Storage Usage Worker¶

The storage usage worker tracks real disk usage per mailbox, enforces storage quotas, and sends alerts when users approach their limits. It works alongside Dovecot's built-in quota plugin but provides a more comprehensive view with organization-level rollups and API access.

What It Does¶

• Calculates real disk usage per mailbox by scanning /var/mail/vhosts/
• Enforces quotas at the mailbox, domain, and organization level
• Sends alerts via webhooks when storage thresholds are crossed (75%, 80%, 95%)
• Caches usage data in Redis for fast API responses
• Provides storage analytics and reporting
• Exposes an API for querying usage and managing quotas

How It Works¶

flowchart LR
    subgraph Worker["Storage Usage Worker :8092"]
        Scanner["Filesystem\nScanner"]
        Cache["Redis\nCache"]
        AlertSvc["Alert\nService"]
        API["Flask API"]
    end

    MailDir["/var/mail/vhosts/"] --> Scanner
    Scanner --> Cache
    Scanner --> MySQL[(MySQL)]
    Scanner --> AlertSvc
    AlertSvc --> Webhooks["Webhook\nDispatcher"]
    Cache --> API
    MySQL --> API

The scanner runs periodically (configurable interval), walks the Maildir tree, sums up file sizes per mailbox, and updates both the cache and database.

API Endpoints¶

GET  /api/storage/usage/{email}          -- Usage for a specific mailbox
GET  /api/storage/usage/domain/{domain}  -- Usage for all mailboxes in a domain
GET  /api/storage/usage/org/{org_id}     -- Usage for all mailboxes in an org
GET  /api/storage/quota/{email}          -- Quota settings for a mailbox
PUT  /api/storage/quota/{email}          -- Update quota for a mailbox
GET  /api/storage/alerts                  -- Recent quota alerts
GET  /health                              -- Health check
GET  /metrics                             -- Prometheus metrics

Example Response¶

{
  "email": "user@example.com",
  "usage_bytes": 2147483648,
  "usage_human": "2.0 GB",
  "quota_bytes": 5368709120,
  "quota_human": "5.0 GB",
  "usage_percent": 40.0,
  "last_updated": "2025-01-15T10:30:00Z"
}

Alert Thresholds¶

Alerts are dispatched via the shared webhook_dispatcher module.

Services Architecture¶

The worker uses a modular service architecture:

Database Tables¶

Configuration¶

Docker Configuration¶

storage_usage:
  build: ./worker/storage_usage
  container_name: storage_usage
  ports:
    - "8092:8092"
  volumes:
    - mail_data:/var/mail/vhosts:ro   # Read-only access to mail storage
  depends_on:
    - mysql
    - redis

Gotchas¶