Skip to content

Upgrade from TheHive 5.x#

Upgrade your existing TheHive On-prem instance from one 5.x version to another.

The upgrade preserves all your data. Even so, performing a full database backup before you start is strongly recommended.

Guide scope

Applies to standalone and cluster deployments installed using packages or Docker Compose. For upgrades from TheHive 4.x or Kubernetes deployments, refer to the dedicated guides.

Before you begin

To ensure a smooth upgrade, make sure you have:

  • A full database backup. See Backup and Restore for instructions.
  • Deactivated any external health checks on TheHive HTTP interface. Otherwise, the supervising system may kill TheHive during the upgrade.
  • A scheduled maintenance window. The upgrade requires stopping TheHive. Depending on the target version, the first launch may also trigger a database evolution—schema and data updates whose duration scales with your database size.
  • Migrated off the Lucene index backend, if applicable. Lucene isn't supported since version 5.1. See Change Index from Lucene to Elasticsearch.
  • Confirmed that your Java, Cassandra, Elasticsearch, and Cortex versions are compatible with your target version of TheHive. See TheHive Installation Software Requirements.
  • Reviewed the release notes for the target version to identify changes that may affect your deployment.

Downgrade limitation

Once upgraded, your instance can't be downgraded. Reverting to a previous version of TheHive 5 requires restoring your data from the backup.

Step 1: Stop TheHive#

Stop TheHive before installing the new version.

Cluster deployments

For cluster deployments, stop all nodes before continuing. Each node must be updated individually before any node is restarted.

sudo systemctl stop thehive

docker compose down

Step 2: Install the new version#

Download RPM, DEB, and ZIP packages directly with tools like wget or curl and install them manually. For Docker, redeploy with the StrangeBee Docker Compose profiles or pull an updated image tag.

All packages are hosted on an HTTPS-secured website and come with a SHA256 checksum and a GPG signature for verification.

Cluster deployments

For cluster deployments, install the new version on each node.

Destination path

The commands below use /tmp/ as the download path. Replace it with the full local directory path where you want to save the files.

  1. Download the installation package along with its SHA256 checksum and signature files.

    • Using wget:

      wget -O /tmp/thehive_5.7.2-1_all.deb https://thehive.download.strangebee.com/5.7/deb/thehive_5.7.2-1_all.deb
wget -O /tmp/thehive_5.7.2-1_all.deb.sha256 https://thehive.download.strangebee.com/5.7/sha256/thehive_5.7.2-1_all.deb.sha256
wget -O /tmp/thehive_5.7.2-1_all.deb.asc https://thehive.download.strangebee.com/5.7/asc/thehive_5.7.2-1_all.deb.asc

      To download a specific version instead of the latest, use the following format:

      wget -O /tmp/<file_name>.deb https://thehive.download.strangebee.com/<major.minor_version>/deb/<file_name>.deb
wget -O /tmp/<file_name>.deb.sha256 https://thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.deb.sha256
wget -O /tmp/<file_name>.deb.asc https://thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.deb.asc
      • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive_5.6.3-1_all.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 5.6.

      Package repository

      For details on package organization and naming conventions, see TheHive Package Repository.

    • Using curl:

      curl -o /tmp/thehive_5.7.2-1_all.deb https://thehive.download.strangebee.com/5.7/deb/thehive_5.7.2-1_all.deb
curl -o /tmp/thehive_5.7.2-1_all.deb.sha256 https://thehive.download.strangebee.com/5.7/sha256/thehive_5.7.2-1_all.deb.sha256
curl -o /tmp/thehive_5.7.2-1_all.deb.asc https://thehive.download.strangebee.com/5.7/asc/thehive_5.7.2-1_all.deb.asc

      To download a specific version instead of the latest, use the following format:

      curl -o /tmp/<file_name>.deb https://thehive.download.strangebee.com/<major.minor_version>/deb/<file_name>.deb
curl -o /tmp/<file_name>.deb.sha256 https://thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.deb.sha256
curl -o /tmp/<file_name>.deb.asc https://thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.deb.asc
      • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive_5.6.3-1_all.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 5.6.

      Package repository

      For details on package organization and naming conventions, see TheHive Package Repository.

  2. Verify the integrity of the downloaded package.

    • Check the SHA256 checksum by comparing it with the provided value.

      a. Generate the SHA256 checksum of your downloaded package.

      sha256sum /tmp/thehive_5.7.2-1_all.deb

      b. Compare the output hash with the official SHA256 value listed in the .sha256 file.

      cat /tmp/thehive_5.7.2-1_all.deb.sha256

      c. If both hashes match exactly, the file integrity is verified. If not, the file may be corrupted or tampered with—don't proceed with installation, and contact the StrangeBee Security team.

    • Verify the GPG signature using the public key.

      a. Download the public key at keys.download.strangebee.com using wget or curl.

      wget -O /tmp/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg

      curl -o /tmp/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg

      b. Import the key into your GPG keyring.

      gpg --import /tmp/strangebee.gpg

      c. Verify the downloaded package signature.

      gpg --verify /tmp/thehive_5.7.2-1_all.deb.asc /tmp/thehive_5.7.2-1_all.deb

      d. Expected result.

      You should see output similar to:

      gpg: Good signature from "TheHive Project (TheHive release key) <support@thehive-project.org>"

      The key fingerprint must match: 0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C

      Expected GPG warning

      gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
      This warning is expected. It means the package is signed with the official TheHive release key, but you haven't marked this key as trusted in your local GPG setup. As long as you see Good signature and the fingerprint matches, the verification is successful. Don't mark our key as globally trusted—the warning is a normal safety reminder and should remain visible.

      If you don't see Good signature, if the fingerprint differs, or if the signature is reported as BAD, don't install the package. This indicates the integrity or authenticity of the file can't be confirmed. Report the issue to the StrangeBee Security team.

  3. Install the package.

    • Using apt-get to manage dependencies automatically:

      sudo apt-get install /tmp/thehive_5.7.2-1_all.deb

    • Using dpkg:

      sudo dpkg -i /tmp/thehive_5.7.2-1_all.deb

Destination path

The commands below use /tmp/ as the download path. Replace it with the full local directory path where you want to save the files.

  1. Download the installation package along with its SHA256 checksum and signature files.

    • Using wget:

      wget -O /tmp/thehive-5.7.2-1.noarch.rpm https://thehive.download.strangebee.com/5.7/rpm/thehive-5.7.2-1.noarch.rpm
wget -O /tmp/thehive-5.7.2-1.noarch.rpm.sha256 https://thehive.download.strangebee.com/5.7/sha256/thehive-5.7.2-1.noarch.rpm.sha256
wget -O /tmp/thehive-5.7.2-1.noarch.rpm.asc https://thehive.download.strangebee.com/5.7/asc/thehive-5.7.2-1.noarch.rpm.asc

      To download a specific version instead of the latest, use the following format:

      wget -O /tmp/<file_name>.noarch.rpm https://thehive.download.strangebee.com/<major.minor_version>/rpm/<file_name>.noarch.rpm
wget -O /tmp/<file_name>.noarch.rpm.sha256 https://thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.noarch.rpm.sha256
wget -O /tmp/<file_name>.noarch.rpm.asc https://thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.noarch.rpm.asc
      • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive-5.6.3-1.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 5.6.

      Package repository

      For details on package organization and naming conventions, see TheHive Package Repository.

    • Using curl:

      curl -o /tmp/thehive-5.7.2-1.noarch.rpm https://thehive.download.strangebee.com/5.7/rpm/thehive-5.7.2-1.noarch.rpm
curl -o /tmp/thehive-5.7.2-1.noarch.rpm.sha256 https://thehive.download.strangebee.com/5.7/sha256/thehive-5.7.2-1.noarch.rpm.sha256
curl -o /tmp/thehive-5.7.2-1.noarch.rpm.asc https://thehive.download.strangebee.com/5.7/asc/thehive-5.7.2-1.noarch.rpm.asc

      To download a specific version instead of the latest, use the following format:

      curl -o /tmp/<file_name>.noarch.rpm https://thehive.download.strangebee.com/<major.minor_version>/rpm/<file_name>.noarch.rpm
curl -o /tmp/<file_name>.noarch.rpm.sha256 https://thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.noarch.rpm.sha256
curl -o /tmp/<file_name>.noarch.rpm.asc https://thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.noarch.rpm.asc
      • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive-5.6.3-1.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 5.6.

      Package repository

      For details on package organization and naming conventions, see TheHive Package Repository.

  2. Verify the integrity of the downloaded package.

    • Check the SHA256 checksum by comparing it with the provided value.

      a. Generate the SHA256 checksum of your downloaded package.

      sha256sum /tmp/thehive-5.7.2-1.noarch.rpm

      b. Compare the output hash with the official SHA256 value listed in the .sha256 file.

      cat /tmp/thehive-5.7.2-1.noarch.rpm.sha256

      c. If both hashes match exactly, the file integrity is verified. If not, the file may be corrupted or tampered with—don't proceed with installation, and contact the StrangeBee Security team

    • Verify the GPG signature using the public key.

      a. Download the public key at keys.download.strangebee.com using wget or curl.

      wget -O /tmp/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg

      curl -o /tmp/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg

      b. Import the key into your GPG keyring.

      gpg --import /tmp/strangebee.gpg

      c. Verify the downloaded package signature.

      gpg --verify /tmp/thehive-5.7.2-1.noarch.rpm.asc /tmp/thehive-5.7.2-1.noarch.rpm

      d. Expected result.

      You should see output similar to:

      gpg: Good signature from "TheHive Project (TheHive release key) <support@thehive-project.org>"

      The key fingerprint must match: 0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C

      Expected GPG warning

      gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
      This warning is expected. It means the package is signed with the official TheHive release key, but you haven't marked this key as trusted in your local GPG setup. As long as you see Good signature and the fingerprint matches, the verification is successful. Don't mark our key as globally trusted—the warning is a normal safety reminder and should remain visible.

      If you don't see Good signature, if the fingerprint differs, or if the signature is reported as BAD, don't install the package. This indicates the integrity or authenticity of the file can't be confirmed. Report the issue to the StrangeBee Security team.

  3. Install the package.

    • Using yum to manage dependencies automatically:

      sudo yum install /tmp/thehive-5.7.2-1.noarch.rpm

    • Using dnf to manage dependencies automatically:

      sudo dnf install /tmp/thehive-5.7.2-1.noarch.rpm

    • Using rpm:

      sudo rpm -ivh /tmp/thehive-5.7.2-1.noarch.rpm

If you prefer more control over where TheHive is installed, need to use it in environments without package managers, or want to avoid dependency issues, you can install TheHive by downloading a ZIP binary package.

Destination path

The commands below use /opt/ as the download path. Replace it with the full local directory path where you want to save the files.

  1. Download the binary package along with its SHA256 checksum and signature files. You can install TheHive anywhere on your filesystem.

    • Using wget

      wget -O /opt/thehive-5.7.2-1.zip https://thehive.download.strangebee.com/5.7/zip/thehive-5.7.2-1.zip
wget -O /opt/thehive-5.7.2-1.zip.sha256 https://thehive.download.strangebee.com/5.7/sha256/thehive-5.7.2-1.zip.sha256
wget -O /opt/thehive-5.7.2-1.zip.asc https://thehive.download.strangebee.com/5.7/asc/thehive-5.7.2-1.zip.asc

      To download a specific version instead of the latest, use the following format:

      wget -O /opt/<file_name>.zip thehive.download.strangebee.com/<major.minor_version>/zip/<file_name>.zip
wget -O /opt/<file_name>.zip.sha256 thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.zip.sha256
wget -O /opt/<file_name>.zip.asc thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.zip.asc
      • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive-5.6.2-1.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 5.6.

      Package repository

      For details on package organization and naming conventions, see TheHive Package Repository.

    • Using curl

      curl -o /opt/thehive-5.7.2-1.zip https://thehive.download.strangebee.com/5.7/zip/thehive-5.7.2-1.zip
curl -o /opt/thehive-5.7.2-1.zip.sha256 https://thehive.download.strangebee.com/5.7/sha256/thehive-5.7.2-1.zip.sha256
curl -o /opt/thehive-5.7.2-1.zip.asc https://thehive.download.strangebee.com/5.7/asc/thehive-5.7.2-1.zip.asc

      To download a specific version instead of the latest, use the following format:

      curl -o /opt/<file_name>.zip thehive.download.strangebee.com/<major.minor_version>/zip/<file_name>.zip
curl -o /opt/<file_name>.zip.sha256 thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.zip.sha256
curl -o /opt/<file_name>.zip.asc thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.zip.asc
      • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive-5.6.2-1.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 5.6.

      Package repository

      For details on package organization and naming conventions, see TheHive Package Repository.

  2. Verify the integrity of the downloaded package.

    • Check the SHA256 checksum by comparing it with the provided value.

      a. Generate the SHA256 checksum of your downloaded package.

      sha256sum /opt/thehive-5.7.2-1.zip

      b. Compare the output hash with the official SHA256 value listed in the .sha256 file.

      cat /opt/thehive-5.7.2-1.zip.sha256

      c. If both hashes match exactly, the file integrity is verified. If not, the file may be corrupted or tampered with—don't proceed with unzipping or installation, and contact the StrangeBee Security team.

    • Verify the GPG signature using the public key.

      a. Download the public key at keys.download.strangebee.com using wget or curl.

      wget -O /opt/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg

      curl -o /opt/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg

      b. Import the key into your GPG keyring.

      gpg --import /opt/strangebee.gpg

      c. Verify the downloaded package signature.

      gpg --verify /opt/thehive-5.7.2-1.zip.asc /opt/thehive-5.7.2-1.zip

      d. Expected result.

      You should see output similar to:

      gpg: Good signature from "TheHive Project (TheHive release key) <support@thehive-project.org>"

      The key fingerprint must match: 0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C

      Expected GPG warning

      gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
      This warning is expected. It means the package is signed with the official TheHive release key, but you haven't marked this key as trusted in your local GPG setup. As long as you see Good signature and the fingerprint matches, the verification is successful. Don't mark our key as globally trusted—the warning is a normal safety reminder and should remain visible.

      If you don't see Good signature, if the fingerprint differs, or if the signature is reported as BAD, don't install the package. This indicates the integrity or authenticity of the file can't be confirmed. Report the issue to the StrangeBee Security team.

  3. Unzip the package.

    Unzip paths

    • Replace /opt/thehive-5.7.2-1.zip with the full path to the ZIP file you downloaded.
    • Replace /opt/ after -d with the directory where you want to extract the contents of the archive.
    unzip /opt/thehive-5.7.2-1.zip -d /opt/
sudo ln -s /opt/thehive-5.7.2-1 /opt/thehive

  4. Prepare the system by creating a dedicated, non-privileged user account to run TheHive. Ensure this user has permission to create log files in /opt/thehive/logs.

    sudo addgroup thehive
sudo adduser --system thehive
sudo chown -R thehive:thehive /opt/thehive
sudo mkdir /etc/thehive
sudo touch /etc/thehive/application.conf
sudo chown root:thehive /etc/thehive
sudo chgrp thehive /etc/thehive/application.conf
sudo chmod 640 /etc/thehive/application.conf

  5. Copy the systemd script into /etc/systemd/system/thehive.service.

    cd /tmp
wget https://raw.githubusercontent.com/TheHive-Project/TheHive/master/package/thehive.service
sudo cp thehive.service /etc/systemd/system/thehive.service

If you deployed using the StrangeBee Docker Compose profiles, pull the latest version of the repository before redeploying. The docker-compose.yml, configuration templates, and helper scripts may have changed between 5.x versions. The version is set in the versions.env file at the root of the repository, with the thehive_image_version variable.

If you used the public image directly, update the image tag to strangebee/thehive:5.7, or to a specific version if you don't want the latest.

Don't use the latest tag

The strangebee/thehive:latest tag is deprecated and remains pinned to TheHive 5.0.x.

(Optional) Step 3: Update the web framework#

Skip this step if you're upgrading from version 5.4 or later.

Cluster deployments

For cluster deployments, update the configuration file on each node.

Starting with version 5.4, TheHive uses Play3/Pekko as the web framework. Depending on your installation and configuration, you may need to update your configuration file. See the Pekko configuration guide for details.

Step 4: Start TheHive#

Cluster deployments

For cluster deployments, start one node first and wait for TheHive to be fully up and running. Then start the remaining nodes one by one.

  1. Start TheHive.

    sudo systemctl start thehive

    docker compose up -d

    First-launch database evolution

    Depending on the target version, the first launch may trigger a database evolution—schema and data updates whose duration scales with your database size.

  2. Verify that TheHive is running.

    sudo systemctl status thehive

    If TheHive is running, the output shows an active status in green.

    docker compose ps

    If TheHive is running, the container shows as Up.

Troubleshooting TheHive

If you run into issues, see the Troubleshooting page.

Step 5: Verify the upgrade#

Open TheHive in your web browser. Confirm that the version in the bottom-left corner matches the version you installed.

Next steps