Configuration

SpamFoo is configured through a combination of command-line arguments, environment variables, and runtime settings in the admin dashboard. This page covers all available options and how they interact.

Configuration Priority

When the same setting is available in multiple places, SpamFoo applies them in the following order (highest priority first):

1. Environment variables - Always take precedence
2. Database settings - Stored in the local SQLite database, managed via the admin dashboard or Settings API
3. Built-in defaults - Used when nothing else is configured

Command-line arguments control paths and startup behavior and are always applied at launch.

Command-Line Arguments

These arguments are passed when starting SpamFoo and control directory paths and startup behavior. All path arguments support ~ expansion for the user's home directory.

Example:

./spamfoo-client --data-dir=/var/lib/spamfoo --models-dir=/opt/spamfoo/models --debug

Environment Variables

Global API

Classification Queue

These settings control how SpamFoo processes classification requests. SpamFoo uses a shared concurrency pool split between real-time (spool) and background classification queues.

Network

Admin Dashboard Settings

Settings stored in the local database can be viewed and modified through the admin dashboard at http://localhost:16253/admin, or through the Settings API. Changes made in this way take effect immediately without restarting SpamFoo.

Queue Settings

These mirror the classification queue environment variables above and allow you to tune concurrency and timeouts at runtime without restarting the service.

Data Retention Settings

Control how long SpamFoo retains classification data and logs locally. Adjusting these settings affects disk usage.

Directory Structure

SpamFoo organizes its data under the base directory (set via --data-dir or the application directory by default):

{data-dir}/
  admin.db              # SQLite database (settings, classifications, aggregates)
  domain_age.db         # Domain reputation cache
  personalization/      # Per-user personalization data
  trained-models/       # ML model files
    active/             # Currently loaded models
  logs/                 # Log files (system, classification, updates, errors)
  etc/                  # Configuration files (license key, installation ID)

Log files use rolling retention with a 30-day window and 50 MB per-file size limit. See Log Management for details on each log type.

Performance Tuning

SpamFoo is designed to run on mail servers with limited resources. The default settings are conservative and work well for most deployments. If you need to adjust performance, start with these guidelines:

Concurrency

The SPAMFOO_MAX_CLASSIFICATION_CONCURRENCY setting (or Queue.MaxConcurrency in the admin dashboard) controls how many emails SpamFoo classifies simultaneously. The default of 2 keeps CPU and memory usage low.

• Low-traffic servers (under 1,000 emails/day): Default of 2 is sufficient. Lower to 1 on lower-core CPUs.
• Medium-traffic servers (1,000-10,000 emails/day): Consider 2-3
• High-traffic servers (10,000+ emails/day): Set to 3+, ensure at least 250 MB of additional available memory per concurrent slot

Timeouts

The spool timeout (SPAMFOO_CLASSIFICATION_QUEUE_TIMEOUT_SECONDS) controls how long a real-time classification request waits in the queue before SpamFoo returns a 503 error. The default of 30 seconds works well for most mail server integrations. If your mail server has a shorter timeout for content filters, reduce this value to match.

Data Retention

On servers with limited disk space, reduce retention periods in the admin dashboard. The most impactful setting is Retention.DayAggregatesDays (default 90 days). Reducing this to 30 days significantly decreases database size on high-volume servers.

Docker Configuration

When running SpamFoo in Docker, pass environment variables with -e flags and mount a persistent volume for data:

docker run -d \
    --name spamfoo \
    -p 16253:16253 \
    -e SPAMFOO_LICENSE_KEY=your-license-key \
    -e SPAMFOO_BIND_ADDRESS=0.0.0.0 \
    -e SPAMFOO_MAX_CLASSIFICATION_CONCURRENCY=4 \
    -v spamfoo-data:/app/data \
    spamfoo/client:latest

Next Steps

• Integrate SpamFoo with your mail server
• Explore the admin dashboard to monitor classifications
• Review Best Practices for production deployment recommendations