Skip to content

Deploy TheHive with Docker Compose#

In this guide, we're going to deploy and configure TheHive On-prem using Docker Compose.

By the end, you'll have a fully functional TheHive instance running in Docker containers.

We provide several deployment profiles depending on your performance requirements on a dedicated GitHub repository, with all services configured automatically.

If you want to use only the TheHive Docker image, get it from Docker Hub. You'll need to install other required services separately.

Guide scope

This guide covers deploying a new instance of TheHive using Docker Compose, with all components hosted on the same server.

It doesn't cover:

Before you begin

To ensure a smooth deployment process, make sure you have:

Step 1: Install required dependencies#

Start by installing the necessary dependencies for deploying TheHive with Docker Compose.

Verify dependencies installation#

Run the following commands to ensure the dependencies are correctly installed:

  • Check the Docker engine version:
docker version
  • Confirm the current user can run Docker commands:
docker run hello-world

For details on post-installation steps and user permissions, see the Docker post-installation guide.

  • Check the Docker Compose plugin version:
docker compose version

Step 2: Clone the GitHub repository#

Next, clone the StrangeBee Docker repository to your local machine:

git clone https://github.com/StrangeBeeCorp/docker.git

Step 3: Choose your deployment profile#

Before proceeding with any commands, take a moment to choose the deployment profile that best fits your needs. We provide three prebuilt profiles, each designed for different use cases and performance requirements.

Profile n°1: Testing environment (TheHive and Cortex)#

Testing only

This profile is for testing purposes only and must never be used in production

Single server deployment of both TheHive and Cortex for testing purposes.

Check the hardware requirements in the Docker Compose deployment section.

Profile n°2: Production environment #1 (TheHive)#

Single server deployment of TheHive for intensive use.

Check the hardware requirements in the Docker Compose deployment section.

Profile n°3: Production environment #2 (TheHive)#

Single server deployment of TheHive for high-performance requirements.

Check the hardware requirements in the Docker Compose deployment section.

Cortex deployment

Similar production deployment profiles are available for Cortex. See Run Cortex with Docker for details.

Step 4: Understand the application stack content#

The Docker Compose file deploys the following components:

  • Cassandra: Database used by TheHive
  • Elasticsearch: Database for Cortex and indexing engine for TheHive
  • TheHive: Main application
  • Cortex: Analyzers and responders engine
  • Nginx: HTTPS reverse proxy

Configuration and data files#

Each container has a dedicated folder for configuration, data, and log files.

├── cassandra
├── certificates
├── cortex
├── docker-compose.yml
├── dot.env.template
├── elasticsearch
├── nginx
├── README.md
├── scripts
└── thehive

Files and folders overview#

Cassandra#

cassandra
├── data
└── logs
  • ./cassandra/data: Database files.
  • ./cassandra/logs: Log files.

Don't modify

Don't manually modify these folders.

Elasticsearch#

elasticsearch
├── data
└── logs
  • ./elasticsearch/data: Database files.
  • ./elasticsearch/logs: Log files.

Don't modify

Don't manually modify these folders.

TheHive#

thehive
├── config
│   ├── application.conf
│   ├── index.conf.template
│   ├── logback.xml
│   └── secret.conf.template
├── data
│   └── files
└── logs
  • ./thehive/config: Configuration files. index.conf and secret.conf are generated automatically when you use the init.sh script.
  • ./thehive/data/files: File storage for TheHive.
  • ./thehive/logs: Log files.

Don't modify

Don't manually modify these folders except for files in config if you know what you're doing.

Cortex#

cortex
├── config
│   ├── application.conf
│   ├── index.conf.template
│   ├── logback.xml
│   └── secret.conf.template
├── cortex-jobs
├── logs
└── neurons
  • ./cortex/config: Configuration files. index.conf and secret.conf are generated automatically when you use the init.sh script.
  • ./cortex/cortex-jobs: Temporary data storage for analyzers and responders.
  • ./cortex/logs: Log files.
  • ./cortex/neurons: Folder for custom analyzers and responders.

Don't modify

Don't manually modify these folders except for files in config if you know what you're doing.

Nginx#

nginx
├── certs
└── templates
    └── default.conf.template
  • ./nginx/templates/default.conf.template: File used to initialize Nginx configuration when the container starts.

Don't modify

Don't manually modify these folders.

Certificates#

This folder is empty by default. The application stack initializes with self-signed certificates.

To use your own certificates, such as certificates signed by an internal authority, create the following files with these exact filenames:

certificates
├── server.crt         ## Server certificate
├── server.key         ## Server private key
└── ca.pem             ## Certificate Authority

Scripts#

scripts
├── check_permissions.sh
├── generate_certs.sh
├── init.sh
├── output.sh
├── reset.sh
├── test_init_applications.sh
├── test_init_cortex.sh
├── test_init_thehive.sh
├── backup.sh
└── restore.sh

The application stack includes several utility scripts:

  • check_permissions.sh: Ensures proper permissions are set on files and folders.
  • generate_certs.sh: Generates a self-signed certificate for Nginx.
  • init.sh: Initializes the application stack.
  • output.sh: Displays output messages called by other scripts.
  • reset.sh: Resets the testing environment. Running this script deletes all data and containers.
  • test_init_applications.sh: Configures TheHive and Cortex by enabling analyzers, integrating Cortex with TheHive, and creating sample data like alerts, observables, and custom fields in TheHive.
  • test_init_cortex.sh: Helper script called by test_init_applications.sh to set up Cortex.
  • test_init_thehive.sh: Helper script called by test_init_applications.sh to set up TheHive.
  • backup.sh: Performs a cold backup of the current environment.
  • restore.sh: Restores the environment from a previously taken backup.

The Docker Compose file deploys the following components:

  • Cassandra: Database used by TheHive
  • Elasticsearch: Indexing engine for TheHive
  • TheHive: Main application
  • Nginx: HTTPS reverse proxy

Configuration and data files#

Each container has a dedicated folder for configuration, data, and log files.

├── cassandra
├── certificates
├── docker-compose.yml
├── dot.env.template
├── elasticsearch
├── nginx
├── README.md
├── scripts
└── thehive

Files and folders overview#

Cassandra#

cassandra
├── data
└── logs
  • ./cassandra/data: Database files.
  • ./cassandra/logs: Log files.

Don't modify

Don't manually modify these folders.

Elasticsearch#

elasticsearch
├── data
└── logs
  • ./elasticsearch/data: Database files.
  • ./elasticsearch/logs: Log files.

Don't modify

Don't manually modify these folders.

TheHive#

thehive
├── config
│   ├── application.conf
│   ├── index.conf.template
│   ├── logback.xml
│   └── secret.conf.template
├── data
│   └── files
└── logs
  • ./thehive/config: Configuration files. index.conf and secret.conf are generated automatically when you use the init.sh script.
  • ./thehive/data/files: File storage for TheHive.
  • ./thehive/logs: Log files.

Don't modify

Don't manually modify these folders except for files in config if you know what you're doing.

Nginx#

nginx
├── certs
└── templates
    └── default.conf.template
  • ./nginx/templates/default.conf.template: File used to initialize Nginx configuration when the container starts.

Don't modify

Don't manually modify these folders.

Certificates#

This folder is empty by default. The application stack initializes with self-signed certificates.

To use your own certificates, such as certificates signed by an internal authority, create the following files with these exact filenames:

certificates
├── server.crt         ## Server certificate
├── server.key         ## Server private key
└── ca.pem             ## Certificate Authority

Scripts#

scripts
├── check_permissions.sh
├── generate_certs.sh
├── init.sh
├── output.sh
├── reset.sh
├── backup.sh
└── restore.sh

The application stack includes several utility scripts:

  • check_permissions.sh: Ensures proper permissions are set on files and folders.
  • generate_certs.sh: Generates a self-signed certificate for Nginx.
  • init.sh: Initializes the application stack.
  • output.sh: Displays output messages called by other scripts.
  • reset.sh: Resets the testing environment. Running this script deletes all data and containers.
  • backup.sh: Performs a cold backup of the current environment. See Backup a Stack Run with Docker Compose for more details.
  • restore.sh: Restores the environment from a previously taken backup. See Restore a Stack Run with Docker Compose for more details.

Step 5: Go to the selected profile#

Navigate to the directory of your chosen profile.

For example, to select the Production environment #1 profile:

cd docker/prod1-thehive

Step 6: Initialize TheHive#

Before starting TheHive, we need to initialize the environment using the provided init.sh script.

This script automates several critical setup tasks:

  • Prompts for a server name to include in the Nginx server certificate.
  • Initializes the secret.conf configuration files for TheHive and Cortex.
  • Generates a self-signed certificate if none exists in the ./certificates directory.
  • Creates a .env file with user/group information and application settings.
  • Generates a random password for Elasticsearch authentication.
  • Verifies file and folder permissions to ensure proper access rights.

Elasticsearch password

If you need to retrieve the Elasticsearch password, check the .env file.

User permissions

TheHive will run under the user account and group that execute the initialization script. Ensure you're using an appropriate user with the necessary permissions.

Execute the initialization script to set up the necessary configurations:

bash ./scripts/init.sh

Step 7: Start TheHive#

Once initialization is complete, start all services using Docker Compose.

docker compose up -d

If TheHive fails to start or you encounter errors, stop the running containers and restart without the -d flag to display real-time logs in your terminal:

docker compose down
docker compose up

Step 8: Access TheHive#

Open your browser and navigate to http://localhost/thehive or use the IP address of the server running Docker Compose.

For additional Docker entrypoint options, see TheHive Docker Entrypoint Settings.

Next steps