Installing SpamFoo

This guide walks through downloading, installing, and verifying SpamFoo on your mail server. SpamFoo is currently distributed as a zip archive for all platforms.

SmarterMail

When running SpamFoo in connection with SmarterMail, no download or installation is necessary. It will automatically download and configure the SpamFoo client.

Prerequisites

Before installing, confirm the following:

  • Your system meets the System Requirements (x64 processor, 2+ cores, 512 MB+ available memory)
  • You have a SpamFoo API key from spamfoo.com (not required for SmarterMail integrations)
  • You have administrative/root access on the server

Download

Download the SpamFoo zip archive for your platform from your SpamFoo Account. Choose the archive matching your operating system:

  • spamfoo-client-###-windows-x64.zip - Windows
  • spamfoo-client-###-linux-x64.tar.gz - Linux

Windows

Extract and Configure

  1. Extract the zip archive to your desired install location (e.g., C:\SpamFoo)
  2. Set your API key using one of these methods:
    • Create a file named sf.key in the SpamFoo directory containing your API key
    • Set the SPAMFOO_LICENSE_KEY environment variable

Run SpamFoo

Start SpamFoo from the command line:

cd C:\SpamFoo
.\spamfoo-client.exe

SpamFoo starts and listens on http://localhost:16253.

Run as a Windows Service

To run SpamFoo as a background Windows Service that starts automatically, use the built-in sc command: 

sc create SpamFoo binPath= "C:\SpamFoo\spamfoo-client.exe" start= auto
sc start SpamFoo

To stop and remove the service:

sc stop SpamFoo
sc delete SpamFoo

Linux

Extract and Configure

sudo mkdir -p /opt/spamfoo
sudo tar -xzf spamfoo-linux-x64.tar.gz -C /opt/spamfoo

Set your API key:

# Option 1: Key file
echo "your-api-key" | sudo tee /opt/spamfoo/sf.key

# Option 2: Environment variable (add to your shell profile or systemd unit)
export SPAMFOO_LICENSE_KEY="your-api-key"

Run SpamFoo

Start SpamFoo directly:

cd /opt/spamfoo
./spamfoo-client

Run as a systemd Service

Create a systemd unit file at /etc/systemd/system/spamfoo.service:

[Unit]
Description=SpamFoo Client
After=network.target

[Service]
Type=notify
WorkingDirectory=/opt/spamfoo
ExecStart=/opt/spamfoo/spamfoo-client
Restart=on-failure
RestartSec=10
User=spamfoo
Environment=SPAMFOO_LICENSE_KEY=your-api-key

[Install]
WantedBy=multi-user.target

Create a dedicated service user and enable the service:

sudo useradd -r -s /usr/sbin/nologin spamfoo
sudo chown -R spamfoo:spamfoo /opt/spamfoo

sudo systemctl daemon-reload
sudo systemctl enable spamfoo
sudo systemctl start spamfoo

Check service status:

sudo systemctl status spamfoo

Docker

Note: Docker support is currently in development.

Initial Configuration

At minimum, SpamFoo needs an API key to operate. Additional configuration is available through environment variables, CLI arguments, and the admin dashboard. Key options include:

  • --data-dir=/path - Override the data directory (SQLite database, personalization data)
  • --models-dir=/path - Override the ML models directory
  • --debug - Enable debug logging
  • SPAMFOO_BIND_ADDRESS - Change the HTTP bind address (default: localhost)

See Configuration for the full list of options.

Post-Install Verification

After starting SpamFoo, open the admin dashboard in your browser:

http://localhost:16253/admin

The dashboard should load and display:

  • Service status (running)
  • License status (activated)
  • Current model version
  • Classification statistics (empty initially)

If the dashboard does not load, check that the process is running and review the log files in the logs/ directory. See Common Issues for troubleshooting steps.

Next Steps

  1. Review and adjust Configuration settings
  2. Integrate SpamFoo with your mail server
  3. Send a test email and confirm it appears in the admin dashboard