Skip to content

Installation Guide — Ubuntu / Debian / Kali

This guide covers installing Faraday Pro or Corporate edition on Debian-based distributions using .deb packages.

For the Community edition, see the Community Installation Guide.

Prerequisites

  • Ubuntu 22.04 LTS, 24.04 LTS, Debian 12+, or Kali Linux (64-bit)
  • Root or sudo access
  • PostgreSQL 12+ (14+ recommended)
  • Redis 6.0+ (7.x recommended)

Step 1 — Install PostgreSQL

Install PostgreSQL from the distribution repositories or the official PostgreSQL repository:

sudo apt-get update
sudo apt-get install -y postgresql

Verify PostgreSQL is running:

sudo systemctl status postgresql

PostgreSQL version

Faraday requires PostgreSQL 12 or higher. PostgreSQL 9.6–11 are end-of-life and unsupported. Check your version with psql --version. If your distribution provides an older version, add the PostgreSQL APT repository to install a supported release.

Step 2 — Install Redis

Install Redis from the distribution repositories:

sudo apt-get install -y redis-server

Verify Redis is running:

sudo systemctl status redis-server

Redis version

Faraday requires Redis 6.0 or higher. The Docker reference image uses Redis 8.4. Check your version with redis-server --version.

Step 3 — Download Faraday

Download the Faraday Server .deb package from portal.faradaysec.com (Pro/Corp editions).

For the Community edition .deb, check the GitHub releases page.

Step 4 — Install the package

sudo dpkg -i ./faraday-server_amd64.deb

Or, to automatically resolve dependencies:

sudo apt-get install -y ./faraday-server_amd64.deb

Step 5 — Add your user to the faraday group

sudo usermod -aG faraday $USER

Log out and back in for the group change to take effect.

Step 6 — Initialize the database

On first installation, initialize the database. This creates tables, runs migrations, and generates an admin user with a random password:

sudo faraday-manage initdb

The initdb command is a convenience wrapper that runs:

  1. faraday-manage create-tables — Creates the database schema
  2. faraday-manage create-superuser — Creates the admin user
  3. faraday-manage migrate — Applies any pending database migrations

Save the generated password. You will use it to log in to the Web UI at http://localhost:5985.

Step 7 — Import license (Pro/Corp only)

sudo faraday-manage import-license

Alternatively, download the license file and extract it to the Faraday doc directory:

tar xvf license-file.tar.gz -C /home/faraday/.faraday/doc/

When renewing a license, remove old license files first:

rm /home/faraday/.faraday/doc/*.lic

Step 8 — Start services

Faraday requires three systemd services running:

# Start and enable the main API server
sudo systemctl start faraday-server
sudo systemctl enable faraday-server

# Start and enable the background task worker (required for vulnerability processing)
sudo systemctl start faraday-worker
sudo systemctl enable faraday-worker

# Start and enable the reports worker (required for executive report generation)
sudo systemctl start faraday-worker-reports
sudo systemctl enable faraday-worker-reports

All three services are required

The faraday-worker service processes background tasks including vulnerability ingestion via Celery. Without it, data imports and scan processing will not work. The faraday-worker-reports service generates executive reports.

Verify Installation

Check that all services are running:

sudo systemctl status faraday-server
sudo systemctl status faraday-worker
sudo systemctl status faraday-worker-reports

Open http://localhost:5985 in your browser and log in with the credentials from Step 6.

Configuration

The server configuration file is located at:

/home/faraday/.faraday/config/server.ini

Key settings for bare-metal installs:

Setting Default Description
port 5985 HTTP API port
bind_address localhost Network interface to bind (use 0.0.0.0 for remote access)
api_token_expiration 43200 (12 hours) API token lifetime in seconds
session_timeout 12 Web session timeout in hours

Docker vs bare-metal defaults

Docker installations use different defaults: api_token_expiration = 604800 (7 days) and session_timeout = 24 hours. If migrating from Docker to bare-metal, adjust these values in server.ini to match your expected behavior.

Systemd Services Reference

Service Purpose Entry Point
faraday-server Main REST API and Web UI faraday-server
faraday-worker Celery background task worker faraday-worker
faraday-worker-reports Executive report generation worker faraday-worker (reports queue)

Two additional entry points are available but not installed as systemd services by default:

Command Purpose
faraday-worker-gevent Alternative Celery worker using gevent for higher concurrency
faraday-start-all Convenience command that starts server + workers together

Next Steps