Faraday Installation Guide — Docker Compose¶

Docker Compose is the easiest and recommended way to run Faraday. This setup includes the Faraday Server, a PostgreSQL database, Redis for task queuing, and dedicated Celery workers for background processing.

Prerequisites¶

• Docker Engine 20.10+
• Docker Compose v2 (the docker compose CLI plugin)

Getting Started — Community Edition¶

1. Get the Docker Compose file¶

Save the docker-compose.yaml file in your working directory. You can download it directly from the Faraday repository:

curl -O https://raw.githubusercontent.com/infobyte/faraday/master/docker-compose.yaml

The Compose file defines the following services:

2. Launch services¶

docker compose up -d

3. Get the admin password¶

On first run, an admin user (faraday) is created with an auto-generated password. Retrieve it from the logs:

docker compose logs faraday-server | grep -i password

4. Access Faraday¶

Open http://localhost:5985 in your browser and log in with username faraday and the password from the logs.

Getting Started — Pro / Corporate Edition¶

1. Download the image¶

Download the latest Docker image from portal.faradaysec.com.

2. Load the image¶

docker load < faraday-docker.tar.gz

3. Configure Docker Compose¶

Use the docker-compose.yaml provided with your Pro/Corp distribution. It includes additional services:

4. Import your license¶

docker compose run --rm import-license

5. Launch services¶

docker compose up -d

Faraday Server is available at http://localhost:5985.

The admin password is automatically generated and displayed in the server logs on first run.

Change Password¶

docker compose run --rm change-password

This prompts you to set a new password for the admin user.

Persistence and Volumes¶

Data is persisted using Docker named volumes:

To use a local folder instead of a named volume (useful for backups or inspection):

x-faraday-volumes: &faraday-volumes
  - "$HOME/.faraday:/home/faraday/.faraday:rw"

Environment Variables¶

The Docker entrypoint accepts the following environment variables:

Configuration Defaults¶

Docker deployments use different configuration defaults than bare-metal installations:

These values are set in ~/.faraday/config/server.ini inside the container. To customize, mount a local server.ini into the container or set environment variables.

Development Mode¶

To work on the Faraday source code with Docker:

1. Configure the Compose file¶

Edit docker-compose.yaml:

• Uncomment the args section with DEV_ENV=1
• Use a custom image name (e.g., faraday-local)
• Map your local repository to /src:

volumes:
  - "/path/to/faraday/cloned/repo:/src"

2. Build and run¶

docker compose build
docker compose up -d

Local code changes are reflected without rebuilding the image.

Health Check¶

The Faraday Server container includes a built-in health check:

GET http://localhost:5985/_api/config

Check container health with:

docker compose ps

Troubleshooting¶

Viewing logs¶

# All services
docker compose logs -f

# Specific service
docker compose logs -f faraday-server

Database connection refused¶

Error: connection to server at 'localhost' (127.0.0.1), port 5432 failed: Connection refused

Cause: The Faraday Server container is trying to connect to localhost instead of the db service.

Fix: Edit ~/.faraday/config/server.ini inside the container and change the connection_string host from localhost to db:

[database]
connection_string = postgresql+psycopg2://postgres:postgres@db/faraday

Worker not starting¶

If faraday-default-worker exits immediately, check that:

1. The Faraday Server is healthy: docker compose ps should show healthy status
2. Redis is running: docker compose logs redis
3. The worker can reach Redis: check celery_broker_url in server.ini

Disk space¶

Docker images, PostgreSQL data, and Redis data consume disk space. Plan for:

• Docker images: ~500 MB per Faraday image
• PostgreSQL data: 40–80 GB depending on vulnerability count
• Redis: minimal (in-memory cache, typically < 1 GB)

Docker Services Reference¶