Faraday Installation Guide with Docker Compose¶

The easiest and recommended way to run Faraday with docker is using Docker Compose. This setup includes the Faraday Server, a PostgreSQL database, Redis for task queuing, and dedicated workers for report generation.

Prerequisites¶

Docker installed.
Docker Compose installed.

Getting Started¶

Community Edition¶

Get docker-compose: You can use the following docker-compose.yaml file to get started quickly. Save it in your working directory:

x-faraday-image: &faraday-image index.docker.io/faradaysec/faraday:latest  # Use official image from Docker Hub registry or, see below for local development
# x-faraday-image: &faraday-image faraday-local  # For local development, use local image built with `docker compose build faraday-server`

x-faraday-volumes: &faraday-volumes
  - "faraday:/home/faraday/.faraday:rw"  # by default, store data in a Docker volume.
  # - "$HOME/.faraday:/home/faraday/.faraday:rw"  # Uncomment to use your whole existing `.faraday` folder. Remember to comment the volume above.
  # - "path_to/faraday/cloned/repo:/src"  # Uncomment and adjust path to your local faraday source code directory if you want to use a local development version.

services:
  db:
    image: postgres:12.7-alpine
    restart: always
    container_name: faraday_db
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=faraday
    ports:
      - '5432'
    volumes:
      - "db:/var/lib/postgresql/data:rw"
  redis:
    image: 'redis:8.4-alpine'
    container_name: faraday_redis
    ports:
      - '6379'
  change-password:
    image: *faraday-image
    profiles: ["manual"]
    command: ["faraday-manage", "change-password", "--username", "faraday"]
    volumes: *faraday-volumes
    depends_on:
      - db
  faraday-default-worker:
    image: *faraday-image
    restart: always
    container_name: faraday_worker
    command: [ "faraday-worker" ]
    volumes: *faraday-volumes
    environment:
      - PGSQL_USER=postgres
      - PGSQL_PASSWD=postgres
      - PGSQL_HOST=db
      - PGSQL_DBNAME=faraday
      - REDIS_SERVER=redis
    depends_on:
      faraday-server:
        condition: service_healthy
  faraday-server:
    build:
      context: .
      # args:
      #  - DEV_ENV= 1  # uncomment to use local code source
    image: *faraday-image
    restart: always
    container_name: faraday_server
    entrypoint: "/entrypoint.sh"
    volumes: *faraday-volumes
    environment:
      - PGSQL_USER=postgres
      - PGSQL_PASSWD=postgres
      - PGSQL_HOST=db
      - PGSQL_DBNAME=faraday
      - REDIS_SERVER=redis
    depends_on:
     - db
     - redis
    ports:
     - "5985:5985"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5985/_api/config"]
      interval: 20s
      timeout: 5s
      retries: 10
volumes:
  db:
    driver: local
  faraday:
    driver: local

Alternatively, you can clone the repository or download the source code. The docker-compose.yaml file is located at the root of the repository.

Launch Services: Run the following command from the root of the repository to start all services in the background:
```
docker compose up -d
```

Pro/Corp Edition¶

Get Faraday docker image: Download the latest pro/corp edition image from portal.faradaysec.com.
Load Images: Load the downloaded Docker images into your system (e.g., faraday-docker.tar.gz):
```
docker load < faraday-docker.tar.gz
```
Get docker-compose: You can use the following docker-compose.yaml file to get started quickly. Save it in your working directory:

x-faraday-image: &faraday-image registry.gitlab.com/faradaysec/faraday:latest  # Use official image from Docker Hub registry or, see below for local development
# x-faraday-image: &faraday-image faraday-local  # For local development, use local image built with `docker compose build faraday-server`

x-faraday-volumes: &faraday-volumes
  - "faraday:/home/faraday/.faraday:rw"  # by default, store data in a Docker volume.
  # - "$HOME/.faraday:/home/faraday/.faraday:rw"  # Uncomment to use your whole existing `.faraday` folder. Remember to comment the volume above.
  # - "path_to/faraday/cloned/repo:/src"  # Uncomment and adjust path to your local faraday source code directory if you want to use a local development version.

services:
  db:
    image: postgres:12.7-alpine
    restart: always
    container_name: faraday_db
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=faraday
    ports:
      - '5432'
    volumes:
      - "db:/var/lib/postgresql/data:rw"
  redis:
    image: 'redis:8.4-alpine'
    container_name: faraday_redis
    ports:
      - '6379'
  change-password:
    image: *faraday-image
    profiles: ["manual"]
    command: ["faraday-manage", "change-password"]
    volumes: *faraday-volumes
    depends_on:
      - db
  import-license:
    image: *faraday-image
    profiles: [ "manual" ]
    command: [ "faraday-manage", "import-license" ]
    volumes: *faraday-volumes
    depends_on:
      - db
  faraday-default-worker:
    image: *faraday-image
    restart: always
    container_name: faraday_worker
    command: [ "faraday-worker" ]
    volumes: *faraday-volumes
    environment:
      - PGSQL_USER=postgres
      - PGSQL_PASSWD=postgres
      - PGSQL_HOST=db
      - PGSQL_DBNAME=faraday
      - REDIS_SERVER=redis
    depends_on:
      faraday-server:
        condition: service_healthy
  faraday-executive-reports-worker:
    image: *faraday-image
    restart: always
    container_name: faraday_executive_reports_worker
    command: [ "faraday-worker", "--queue", "executive_reports_queue", "--concurrency", "1" ]
    volumes: *faraday-volumes
    environment:
      - PGSQL_USER=postgres
      - PGSQL_PASSWD=postgres
      - PGSQL_HOST=db
      - PGSQL_DBNAME=faraday
      - REDIS_SERVER=redis
    depends_on:
      faraday-server:
        condition: service_healthy
  faraday-server:
    build:
      context: .
      # args:
      #  - DEV_ENV= 1 # uncomment to use local code source
    image: *faraday-image
    restart: always
    container_name: faraday_server
    entrypoint: "/entrypoint.sh"
    volumes: *faraday-volumes
    environment:
      - PGSQL_USER=postgres
      - PGSQL_PASSWD=postgres
      - PGSQL_HOST=db
      - PGSQL_DBNAME=faraday
      - REDIS_SERVER=redis
    depends_on:
     - db
     - redis
    ports:
     - "5985:5985"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5985/_api/config"]
      interval: 20s
      timeout: 5s
      retries: 10
volumes:
  db:
    driver: local
  faraday:
    driver: local

Download License: Before launching the services, you can download and install your license by running:
```
docker compose run --rm import-license
```
The process will prompt you for your portal.faradaysec.com credentials.
Launch Services: Run the following command from the root of the repository to start all services in the background:
```
docker compose up -d
```

Faraday Server will be available at http://localhost:5985.

Note

The admin password is automatically generated and will be displayed in the logs the first time you run it. If you can't find it, you can change the password following the instructions in the Change Password section.

Change Password¶

To change the default Faraday user's password, you can use the change-password service included in the Docker setup:

docker compose run --rm change-password

The default configuration orchestrates the following components:

Service	Description
`faraday-server`	The main API.
`db`	PostgreSQL 12 database for persistent storage.
`redis`	Message broker for asynchronous tasks.
`faraday-worker`	Default worker for processing background tasks.
`faraday-executive-reports-worker` (pro/corp edition)	Dedicated worker for generating executive reports.

Persistence and Volumes¶

By default, Docker Compose uses named volumes to ensure your data persists even if containers are deleted:

faraday: Stores configuration, logs, and evidence in /home/faraday/.faraday.
db: Stores the PostgreSQL database files.

If you wish to use a local folder instead of a Docker volume for Faraday's home, you can modify the x-faraday-volumes section in the YAML:

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

Development Mode (Local Changes)¶

If you are a developer and want to see your code changes reflected in the containers immediately, you can build a development environment using your local repository.

1. Configure docker-compose.yaml¶

To enable development mode, you need to uncomment the following sections in your docker-compose.yaml:

Build Arguments: Under faraday-server, uncomment the args section and the - DEV_ENV=1 line. This tells the Dockerfile to install Faraday in editable mode (pip install -e .).
Image Name: Uncomment and use a custom image name (e.g., faraday-local) instead of the official registry image.

Source Volume: Under x-faraday-volumes, uncomment the line mapping your local repository path to /src:

x-faraday-volumes: &faraday-volumes
  - "faraday:/home/faraday/.faraday:rw"
  # - "$HOME/.faraday:/home/faraday/.faraday:rw"
  - "/path/to/faraday/cloned/repo:/src"

2. Build and Run¶

Build the local image with the development flag:

docker compose build

Then start the services:

docker compose up -d

Now, any change you make in your local repository will be automatically picked up by the Faraday Server inside the container without requiring a rebuild, thanks to the editable installation and the volume mapping.

Troubleshooting¶

Viewing Logs¶

To see the logs of all services or a specific one:

docker compose logs -f

docker compose logs -f faraday-server

Database Connection Refused (Existing server.ini)¶

If you see an error like this in the logs:

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) connection to server at "localhost" (127.0.0.1), port 5432 failed: Connection refused

And you are mounting an existing .faraday folder from your host, it is likely that your server.ini is still trying to connect to localhost.

Solutions: 1. If using the Docker db service: Edit your ~/.faraday/config/server.ini and update the connection_string. Change localhost to db (the name of the service in Docker Compose). 2. If using a host PostgreSQL: Ensure your PostgreSQL is listening on the correct interface (not just 127.0.0.1) and that your firewall allows connections from the Docker network. You might need to use your host's IP address in the connection_string.

Next Steps¶

We highly recommend you to check our First Steps guide once the server is up.