Install SpamFoo Client

This page shows how to install SpamFoo Client on your mail server or next to it, add your license key, sign in to the dashboard, and check that it works.

Before You Start

• Check that your server meets the System Requirements.
• Make sure you can sign in to the server as an administrator (Windows) or as root (Linux).
• Get your license key. Sign in to your SpamFoo account, go to Licenses, and open your license. Copy the key and save it in a file on the server, such as /root/spamfoo-key.txt, or click Download sf.key.
• The Downloads page in your SpamFoo account has the install commands and the current files for each kind of install. Get every SpamFoo Client download there.

Choose How to Install

• Docker: runs on any Linux host with Docker. Everything SpamFoo Client keeps is stored in one volume.
• Archive: a zip file for Windows, or a tarball for Linux systems the package doesn't support. You set up the service yourself.

The Linux package, the Docker steps, and the Linux archive steps on this page run SpamFoo Client in standalone mode, the mode for a SpamFoo Client that runs on its own instead of being started by SmarterMail.

For the difference, see Mode in Configure SpamFoo Client.

Install With Docker

The Downloads page in your SpamFoo account shows these steps and the current version. The spamfoo/spamfoo-client image runs on Linux hosts with x86_64 processors. Everything SpamFoo Client keeps is stored in one volume mounted at /data.

Start It With Docker Compose

1. In an empty folder, create a file named spamfoo.env with your license key, and keep it private:

   SPAMFOO_LICENSE_KEY=paste-your-license-key-here

   chmod 600 spamfoo.env

2. Save this as compose.yml next to it:

   name: spamfoo
   services:
     spamfoo-client:
       container_name: spamfoo-client
       image: spamfoo/spamfoo-client:latest
       restart: unless-stopped
       stop_grace_period: 30s
       env_file: spamfoo.env
       environment:
         SPAMFOO_MODE: standalone
         SPAMFOO_PUBLIC_URL: http://127.0.0.1:16253
       ports:
         - "127.0.0.1:16253:16253"
       volumes:
         - spamfoo-data:/data
   volumes:
     spamfoo-data: {}

3. Start it:

   docker compose up -d

4. Make a one-time sign-in link, open it, and click Continue:

   docker compose exec spamfoo-client spamfoo-client login-link

Each part of the compose file matters:

• SPAMFOO_MODE: standalone turns on standalone mode. The image doesn't set it, so a container started without it runs the way older versions did.
• restart: unless-stopped starts SpamFoo Client again when it stops to recover from some errors.
• stop_grace_period: 30s gives SpamFoo Client time to finish the messages it's scanning. Docker's default of 10 seconds is too short.
• The port is published on 127.0.0.1, so only the Docker host can connect.
• SPAMFOO_PUBLIC_URL is the address in sign-in links. Change it if you open the dashboard at another address.

To add the license key later instead of in spamfoo.env, save it in a file and run:

docker compose exec -T spamfoo-client spamfoo-client activate --stdin < spamfoo-key.txt

It takes effect without a restart.

Start It With docker run

Use the same spamfoo.env file without Compose:

docker run -d --name spamfoo-client --restart unless-stopped --stop-timeout 30 \
    -e SPAMFOO_MODE=standalone --env-file spamfoo.env \
    -p 127.0.0.1:16253:16253 -v spamfoo-data:/data \
    spamfoo/spamfoo-client:latest

Then make a sign-in link with docker exec spamfoo-client spamfoo-client login-link --url=http://127.0.0.1:16253.

Set the Proxy Secret

The proxy secret is the password your mail server sends with every request. If you don't set one, SpamFoo Client creates a random one in /data/etc/sf.proxysecret the first time it starts. To choose your own, add SPAMFOO_PROXY_SECRET=your-secret to spamfoo.env before the first start. See Proxy Secret.

Accept Mail From Other Servers

To let a mail server on another machine reach the container, publish the port on an address that machine can reach, such as "16253:16253" in the compose file or -p 16253:16253 with docker run. Then allow only your mail servers through the host's firewall.

Use a Folder on the Host

The container runs as user ID 10001. If you mount a host folder instead of a named volume, give that user the folder first:

sudo mkdir -p /srv/spamfoo
sudo chown -R 10001:10001 /srv/spamfoo

Then use /srv/spamfoo:/data as the volume.

Pick an Image Tag

• latest is always the newest release.
• A version tag, such as 1.2.3, stays on that release.
• A major or minor tag, such as 1 or 1.2, moves to the newest release in that line.

To update, see Update Docker.

Install From the Archive

Choose your platform.

sha256sum spamfoo-client-<version>-linux-x64.tar.gz

sudo useradd --system --home-dir /var/lib/spamfoo --shell /usr/sbin/nologin spamfoo
sudo mkdir -p /opt/spamfoo /var/lib/spamfoo /etc/spamfoo
sudo tar -xzf spamfoo-client-<version>-linux-x64.tar.gz -C /opt/spamfoo
sudo chown -R spamfoo:spamfoo /opt/spamfoo /var/lib/spamfoo
sudo chmod 0750 /var/lib/spamfoo

SPAMFOO_MODE=standalone
SPAMFOO_BIND_ADDRESS=127.0.0.1

sudo chown root:spamfoo /etc/spamfoo/spamfoo.conf
sudo chmod 0640 /etc/spamfoo/spamfoo.conf

sudo /opt/spamfoo/spamfoo-client activate --data-dir=/var/lib/spamfoo --file=/root/spamfoo-key.txt

Check the Install

SpamFoo Client downloads its models the first time it starts with a license key. This can take a few minutes.

1. On the server, check that SpamFoo Client is ready to classify mail:

   curl http://localhost:16253/health/ready

   The answer is {"status":"ready","contract":1} when it's ready. Until then, it lists the reasons, such as models_loading or not_activated (no license key). See Check Health. With the Linux package or Docker, you can run spamfoo-client status instead.

2. Sign in to the dashboard with a sign-in link, as shown above, or open http://localhost:16253/admin/ and paste the proxy secret.
3. Go to System > Status.
4. Check that the status line at the top says API connected.
5. Check that the License card shows your plan with the status Active.
6. Check that the Versions card lists a version for the client and for each model.

The proxy secret is a random password SpamFoo Client creates the first time it starts, unless you set SPAMFOO_PROXY_SECRET. Find it here:

If the dashboard doesn't load, check that SpamFoo Client is running and look at the log files in the logs folder of the data directory. See Fix Common Problems and Monitor Logs and Health.

Next Steps

1. Review the settings in Configure SpamFoo Client.
2. Connect your mail server. See How Integration Works.
3. Send a test message and find it in the admin console. See Use the Admin Console.