Skip to content

Getting started

Follow this guide to get fltr running with one Block Rule and one Allow Upstream.

Every install path needs the same two things: a JSON file containing the Block Rules and an HTTP service to receive allowed requests.

Install

fltr ships as a pre-built binary, a Docker image, and can be built from source.

Pre-built binary

Download the binary for your platform from the releases page.

Tip

Rename the downloaded binary to fltr, which is also the name used in the following steps.

Warning

Before continuing, make sure to add the execute permission, which allows the binary to run at all. It can be added by using this command:

chmod +x fltr

Docker

Images are published to ghcr.io/kfmndev/fltr for linux/amd64 and linux/arm64.

See Docker for compose setup and image tags.

From source

Build with Go 1.25 or newer:

go build -o fltr .

Minimal setup

Create a block_rules.json with a single Block Rule:

block_rules.json
{
    "credentials": ["password", "secret"]
}

Set the Allow Upstream and run fltr:

Warning

The following commands only work, if fltr has been added to the path. Adjust the path, depending on how you installed fltr. If the binary lives in the current directory change fltr to ./fltr.

FLTR_ALLOW_UPSTREAM=http://allow.example.com \
fltr

Due to Docker's isolation, the setup differs: the Block Rules file must be mounted, the environment variable set explicitly, and the internal port mapped to a host port.

docker run -d \
  --name fltr \
  -p 8080:8080 \
  -v "$PWD/block_rules.json":/config/block_rules.json:ro \
  -e FLTR_ALLOW_UPSTREAM=http://allow.example.com \
  ghcr.io/kfmndev/fltr

For more details or an example Docker Compose configuration, see Docker.

By default fltr listens on :8080 and reads block_rules.json from the current directory. Both are configurable via Environment variables.

Try a request

With the example configuration running, send a request that matches the credentials Block Rule:

curl -X POST http://localhost:8080 \
    -H 'Content-Type: text/plain' \
    -H 'Title: account details' \
    -d 'password secret'

A request whose Searchable Content contains every term of a Block Rule is blocked. With no Block Upstream configured, fltr answers 200 Request blocked, discarded.

Send a request that matches no Block Rule to route it to the Allow Upstream:

curl -X POST http://localhost:8080 \
    -H 'Content-Type: text/plain' \
    -d 'hello service'

See Block Rules to learn more about the matching or have a look at the request flow in How it works. HTTP behavior documents every response fltr produces itself.