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

GPU Acceleration

Servers with an NVIDIA GPU can offload part of the ML workload to the GPU. This is normally controlled from the admin dashboard, with a few environment variables available for automated deployments. See GPU Acceleration for the full setup guide and variable list.

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.

Advanced Settings

Found in the Advanced section of the Settings page. See Speedup Optimizations below before turning this on.

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

Speedup Optimizations

The Enable Speedup Optimizations switch, in the Advanced section of the Settings page, changes how the classification models use the server. It is off by default. Turning it on takes effect on the next message classified. No restart is needed.

Most of the time spent scoring a message goes into the model that reads the message text. With the switch off, that model shares a small pool of threads with the other models and leaves most of the server's cores free for mail delivery. With the switch on, it gets its own pool of threads that can use every core on the server, and the model runtime turns on additional optimizations and memory pooling. Classifications do not change. The same message gets the same result either way. Only the time it takes to score it changes.

In our testing on a production mail server, a full mailbox re-scan finished up to about 20 percent faster with the switch on and Queue.MaxConcurrency set to 2. Results vary by server. The gain is largest on servers where every core runs at the same speed, and smaller on servers with a mix of fast and slow cores or where most of the time goes to reading mail rather than scoring it.

There is no environment variable for this switch. Set it in the admin dashboard, or through the Settings API as Features.OnnxOptimizations for scripted and Docker deployments. The value is stored in the local database, so it survives restarts and container recreation as long as the data volume is kept.

Before turning it on, consider the following:

• CPU: While a message is being scored, SpamFoo will use every core on the server. On a busy mail server this competes with mail delivery. If delivery slows down or CPU stays high after turning the switch on, turn it off again.
• Memory: The model runtime keeps memory between messages instead of releasing it, so SpamFoo's memory use will be higher and will stay higher. Leave the switch off on servers that are already short on memory.
• Concurrency: With the switch on, each message already uses every core, so a high Queue.MaxConcurrency makes messages compete for the same threads and can be slower than a lower value. Start at 2. If scanning gets slower rather than faster, lower the concurrency before turning the switch off.
• GPU servers: The switch also changes the memory settings used by the GPU runtime. If you use GPU acceleration, watch memory after turning it on.

To check the effect, compare Average Scan Time on the Mail Health page before and after the change.

When a GPU is the better option

If the server has an NVIDIA GPU, GPU Acceleration is the better way to speed up classification, and it does not need the Speedup Optimizations switch to get there.

The reason comes down to what kind of work the model does. Scoring a message is mostly matrix multiplication, which means doing the same small calculation many thousands of times at once. A CPU has a handful of powerful cores built to run one task after another as fast as possible. A GPU has thousands of simple cores built to run the same calculation across a large block of numbers at the same time. That is exactly the shape of the work the model needs, so the GPU finishes each message far sooner than the CPU can, even when the CPU is given every core it has.

The other benefit is what it does for the rest of the server. With the Speedup Optimizations switch, faster scanning comes from taking CPU time away from mail delivery. With a GPU, the scoring moves off the CPU entirely, so mail delivery and classification stop competing for the same cores. The CPU stays free for the mail server, and SpamFoo still handles the smaller parts of each classification on the CPU with the shared thread pool.

GPU acceleration is turned on from the Performance section of the same Settings page. SpamFoo downloads what it needs on its own, so the only requirement is the NVIDIA driver. If the toggle cannot be turned on, the server does not have a supported GPU, and the Speedup Optimizations switch is the option to use instead.

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