Skip to content

Deploy TheHive with Docker Compose#

Deploy and configure TheHive On-prem using Docker Compose.

Two deployment profiles for production environments are available on a dedicated GitHub repository, with all services configured automatically.

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

Trying out TheHive?

This guide covers production deployments only. To trial TheHive with sample data, see Deploy a Demo Docker Environment.

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:

Security considerations

Learn how TheHive handles data protection and safeguards your information.

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. Two prebuilt profiles are available for production environments, each designed for different use cases and performance requirements.

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

Single server deployment of TheHive for standard production workloads.

Check the hardware requirements in the Docker Compose deployment section.

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

Single server deployment of TheHive for high-performance or resource-intensive workloads.

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: Review the application stack#

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 environment. Running this script deletes all data and containers.
  • backup.sh: Performs a cold backup of the current environment. See # Perform a Cold Backup for a Stack Running with Docker Compose for more details.
  • restore.sh: Restores the environment from a previously taken backup. See Restore a Cold Backup for a Stack Running 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, initialize the environment using the provided init.sh script.

bash ./scripts/init.sh

This script automates several critical setup tasks:

  • Prompts for a server name to include in the Nginx server certificate.
  • Initializes the secret.conf and index.conf configuration files for TheHive.
  • 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. That user must have read/write access to the mounted host directories created during initialization.

Step 7: Start TheHive#

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

docker compose up -d

Check that all containers are running.

docker compose ps

All services should show a running status. 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#

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

Then follow the instructions to perform the first login.

Next steps