Scaling Guide¶

When to scale, what to scale, and how — within the single-host Docker Compose model this stack is built around.

Signs You Need to Scale¶

Before scaling anything, confirm you actually have a bottleneck:

Note: Always optimize before you scale. Throwing hardware at a bad query or misconfiguration is expensive and doesn't fix the root cause.

What Can and Cannot Scale Horizontally¶

This distinction is architectural, not aspirational:

Scaling the Stateless Services¶

api, webhooks, and tracking are the services prepared for replication: the production override resets their fixed container_name and host ports precisely so multiple replicas can run.

# Temporarily run a third api replica
docker compose -f docker-compose.yml -f docker-compose.prod.yml \
  up -d --scale api=3 --no-deps api

To make it permanent, raise deploy.replicas for the service in docker-compose.prod.yml:

  api:
    deploy:
      replicas: 3        # was 2
      resources:
        limits:
          memory: 512M

Traefik discovers all replicas of api automatically and load-balances api.<DOMAIN> across them. deployment/deploy.sh rolls exactly these three services on every deploy (scale up alongside the old container, confirm health, then retire the old one).

Database Scaling¶

MySQL is usually the hardest bottleneck to fix because it's stateful.

Step 1: Optimize First¶

-- Find slow queries
SELECT * FROM sys.statements_with_full_table_scans
ORDER BY exec_count DESC LIMIT 10;

-- Tune buffer pool (~70% of available RAM for a dedicated DB host)
SET GLOBAL innodb_buffer_pool_size = 4294967296;  -- 4GB

Raise the production memory limit for mysql in docker-compose.prod.yml (2 GB by default) to match.

Connection pooling is tunable in .env (DB_POOL_SIZE, DB_MAX_OVERFLOW, DB_POOL_TIMEOUT, DB_POOL_RECYCLE).

Step 2: Move to a Managed Database¶

This is the supported "big" move, and it has a dedicated override file. docker-compose.cloud.yml replaces the local mysql and redis containers with no-op stubs and points every service at remote hosts:

# .env
DB_HOST=your-instance.xxxx.rds.amazonaws.com
DB_PORT=3306
REDIS_HOST=your-cluster.xxxx.cache.amazonaws.com
REDIS_PORT=6379

./start.sh cloud
# or, combined with the production override:
docker compose -f docker-compose.yml -f docker-compose.cloud.yml -f docker-compose.prod.yml up -d

A managed MySQL brings read replicas, automated failover, and point-in-time recovery without this stack having to implement them.

Redis¶

A single Redis instance handles hundreds of thousands of operations per second — clustering is far beyond this stack's needs. If Redis becomes a problem, it is almost always memory:

docker compose exec redis redis-cli info memory | head -5

The container already runs with --maxmemory 256mb --maxmemory-policy allkeys-lru; raise the maxmemory in the redis service command: (and the prod memory limit) if evictions hurt hit rates. Or move to a managed Redis via docker-compose.cloud.yml as above.

Mail Throughput¶

Outbound throughput is rarely limited by Postfix's capacity — it is limited by how fast receiving ISPs will accept your mail. That is what the delivery_optimizer service manages: per-ISP throttling, IP warming schedules, and bounce processing. If the queue grows with deferrals from specific providers, the fix is reputation and pacing, not a second Postfix.

For genuinely independent capacity (or a separate sending reputation), deploy a second complete stack on a second host with its own IP and hostname, and split domains or tenants between them. Multiple MX records pointing at the two hosts give inbound redundancy. There is no supported shared-Maildir multi-Postfix topology.

Scaling Roadmap¶

graph TD
    A[Single server<br/>Docker Compose] -->|Growing pains| B[Optimize<br/>indexes, buffer pool, pools]
    B -->|API bottleneck| C[More api/webhooks/tracking replicas]
    C -->|DB bottleneck| D[Managed MySQL + Redis<br/>docker-compose.cloud.yml]
    D -->|Sending reputation / capacity| E[Second full stack on a second host<br/>split tenants or domains]

Capacity Planning¶

Track these to predict when you'll need to scale:

# Are all services up?
sum(up == 0)

# MySQL connection pressure
mysql_global_status_threads_connected / mysql_global_variables_max_connections

# Redis memory pressure
redis_memory_used_bytes / redis_memory_max_bytes

# Host CPU/disk come from `docker stats` and `df` (no node-exporter is deployed)

Mail volume itself lives in the mail_logs table (populated by the log_ingestor) and the analytics service — the console and Grafana's mail_overview dashboard chart it.

Tip: Review capacity monthly. Scale proactively when sustained growth approaches your current ceiling — and see Guides > Scaling to Millions for the long-horizon view.