Skip to content

Installation

Philter Diffuse runs from its Docker image, or from a checkout of its repository with Python. It is not published to PyPI.

Prerequisites

Before installing Philter Diffuse, ensure your system meets the following requirements:

  • Python: Version 3.12 is tested, in CI and in the Docker image. The current OpenDP release requires 3.10 or later.
  • pip: The standard Python package manager.
  • MongoDB (Optional): If you plan to use MongoDB as a data source, ensure it's installed and accessible from your environment.
  • Docker (Optional): If you prefer to run the application in a container.

Direct Installation

  1. Clone the Repository: bash git clone https://github.com/philterd/philter-diffuse.git cd philter-diffuse

  2. Create a Virtual Environment (Recommended): It's best practice to use a virtual environment to manage dependencies and avoid conflicts with other projects. bash python -m venv venv source venv/bin/activate # On macOS/Linux # venv\Scripts\activate # On Windows

  3. Install Dependencies: The core dependencies for Philter Diffuse include opendp, pymongo, and other support libraries. Install them using the provided requirements.txt: bash pip install -r requirements.txt

Docker Installation

Docker provides an isolated and consistent environment for running Philter Diffuse, eliminating potential "it works on my machine" issues.

1. Get the Docker Image

Pull the image from Docker Hub:

docker pull philterd/philter-diffuse:0.1.0

To build it from a checkout instead, run this from the root of the project directory, and use philter-diffuse as the image name in the commands below:

docker build -t philter-diffuse .

2. Run the Container

You can run the container manually, or from a checkout use the provided run-docker.sh script, which builds the image and automates common volume mounts for data processing.

Example: Using the provided script

./run-docker.sh

Example: Running manually with volume mounts The image's entrypoint is main.py, so arguments after the image name are Philter Diffuse's options. It runs in /data, and the image sets PHILTER_DIFFUSE_BUDGET_FILE to /data/privacy_budget.json: mount a directory there to hold the input, the output, and the budget.

docker run --rm --user "$(id -u):$(id -g)" -v $(pwd)/data:/data \
           philterd/philter-diffuse:0.1.0 \
           --input pii_counts.json \
           --source claims-2026 \
           --pii-types ssn,age,zipcode,creditcard \
           --output privatized_counts.csv

The image runs as an unprivileged user (UID 1000), not root. --user "$(id -u):$(id -g)" runs it as you, so it can write to a directory you own. A Docker named volume needs no --user.

Always mount /data. The spent privacy budget is kept in /data/privacy_budget.json, so without the mount it is lost when the container exits and the next run starts with a fresh budget, which defeats --budget-ceiling.

Example: Reading counts from a Philter container To read counts from a Philter container through its API (Philter 4.0 or later), attach both containers to one Docker network and address Philter by its alias philter, which is in the subject alternative name of the self-signed certificate Philter's image generates. Export that certificate into data/ first (see Usage).

docker network create philter-net
docker network connect --alias philter philter-net <philter-container>
docker run --rm --network philter-net --user "$(id -u):$(id -g)" -v $(pwd)/data:/data \
           -e PHILTER_API_KEY \
           philterd/philter-diffuse:0.1.0 \
           --philter-url https://philter:8080 \
           --philter-ca-cert philter.pem \
           --pii-types ssn,email-address,phone-number \
           --output privatized_counts.csv

-e PHILTER_API_KEY passes the key from your shell's environment without putting it on the command line. The budget is keyed by the URL, so keep using the same --philter-url for a deployment: https://philter:8080 and https://localhost:8080 are separate budget entries.

Verification

After installation, verify that Philter Diffuse is ready to use by running the help command:

python main.py --help

You should see a list of available command-line options and their descriptions.