Skip to content

Installation Guide — Community Edition

The Faraday Community edition can be installed via Docker Compose (recommended), PyPI, or from source.

Docker Compose is the simplest way to run the Community edition. See the Docker Installation Guide for full instructions.

Quick start:

# Clone the repository
git clone https://github.com/infobyte/faraday.git
cd faraday

# Launch all services
docker compose up -d

# Check for the auto-generated admin password
docker compose logs faraday-server | grep -i password

This starts PostgreSQL, Redis, the Faraday Server, and a Celery worker.

Method 2 — PyPI Install

Prerequisites

  • Python 3.9+ (3.11 recommended)
  • PostgreSQL 12+ (14+ recommended), running and accessible
  • Redis 6.0+ (7.x recommended), running and accessible
  • System packages for building Python extensions:
# Ubuntu / Debian
sudo apt-get install -y python3-dev build-essential libpq-dev libssl-dev \
    libsasl2-dev libldap2-dev libmagic1

# RHEL / CentOS
sudo dnf install -y python3-devel gcc postgresql-devel openssl-devel \
    openldap-devel cyrus-sasl-devel file-libs

Install Faraday

It is strongly recommended to use a virtual environment:

python3 -m venv faraday-venv
source faraday-venv/bin/activate
pip install faradaysec

Optional extras

Additional packages for extended functionality:

pip install beautifulsoup4 selenium

Method 3 — Source Install

Prerequisites

Same system dependencies as the PyPI method above.

Clone and install

git clone https://github.com/infobyte/faraday.git
cd faraday
python3 -m venv venv
source venv/bin/activate
pip install .

For development with editable install:

pip install -e .
pip install -r requirements_dev.txt

Post-Installation Setup (PyPI and Source)

After installing via pip or source, you must configure the database and start the required services manually.

1. Ensure PostgreSQL is running

Faraday needs a PostgreSQL database. If you don't have one, install and start PostgreSQL:

# Ubuntu / Debian
sudo apt-get install -y postgresql
sudo systemctl start postgresql

2. Ensure Redis is running

Faraday uses Redis as the Celery message broker for background task processing. Without Redis, Celery workers will fail to start.

# Ubuntu / Debian
sudo apt-get install -y redis-server
sudo systemctl start redis-server

Redis is required

Unlike the Docker Compose setup (which includes Redis automatically), bare-metal and pip installs require you to install and run Redis separately. Celery workers depend on Redis for task queuing.

3. Initialize the database

faraday-manage initdb

This creates the database schema, an admin user with an auto-generated password, and applies migrations.

The initdb command is equivalent to running:

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

4. Start the server

As a systemd service (if installed system-wide):

sudo systemctl start faraday-server
sudo systemctl enable faraday-server

sudo systemctl start faraday-worker
sudo systemctl enable faraday-worker

As foreground processes (useful for development or virtualenv installs):

# Terminal 1: Start the server
faraday-server

# Terminal 2: Start the Celery worker
faraday-worker

Or use the convenience command to start everything at once:

faraday-start-all

The worker is required

You must run faraday-worker alongside faraday-server. The worker processes background tasks including vulnerability ingestion, scan imports, and statistics generation via Celery. Without it, these operations will silently queue up and never execute.

5. Access Faraday

Open http://localhost:5985 in your browser and log in with the credentials generated during initdb.

Console Entry Points

The faradaysec package installs the following commands:

Command Purpose
faraday-server Start the Faraday API server
faraday-manage Administrative CLI (database, users, settings, migrations)
faraday-worker Start a Celery background worker
faraday-worker-gevent Start a Celery worker using gevent (higher concurrency)
faraday-start-all Start server + workers together

Configuration

The default configuration file is created at:

~/.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
api_token_expiration 43200 (12 hours) API token lifetime in seconds
session_timeout 12 Web session timeout in hours
celery_broker_url redis Celery message broker URL
celery_backend_url redis Celery result backend URL

Elasticsearch (Optional)

Faraday has optional Elasticsearch integration for advanced search capabilities. If you plan to use it, install Elasticsearch 7.16+ and configure the ELK settings via faraday-manage settings.

Next Steps