Manual Upgrade Guide — Diskover v2.4+ (RHEL/Rocky/AlmaLinux)

Upgrade Path: Diskover v2.4.x or later → newer Diskover release
Deployment Method: Manual RPM (dnf)
Platform: RHEL / Rocky Linux / AlmaLinux 8.x, 9.x, or 10.x

Prefer to automate this? Most production environments should use Ansible — see Running Playbooks — Upgrades for the playbook-driven equivalent of this procedure. This page is for environments where Ansible is not an option and the upgrade must be performed by hand.

Overview

This guide covers upgrading an existing Diskover v2.4.x or later deployment to a newer Diskover release on RHEL-based Linux using manual RPM commands. By the end of this guide, your environment will be running the new Diskover version with all existing configuration, indices, and licenses preserved.

What this guide covers:

• Pre-upgrade checks and backups

• Updating the JFrog Artifactory repository for the new version

• Verifying / creating the Diskover Python virtual environment (/opt/python-venv-diskover) if it is not already present

• Upgrading Diskover Web, Diskover Admin, Diskoverd, scanners, plugins, and file actions on the appropriate hosts

• Maintaining the DISKOVER_ENCRYPT_SECRET_KEY Fernet key on diskover-admin and diskoverd systemd unit files

• Post-upgrade verification, service startup, and rollback

What this guide does NOT cover:

• Fresh installations — see the Manual Installation Guide — Full Stack (RHEL/Rocky Linux)

• Major migration upgrades from v2.2.x — see the Diskover 2.2.x to 2.5.x+ Upgrade Process (RHEL) page (those upgrades include Elasticsearch, PHP, Python venv, and Diskover Admin first-time setup)

• Ansible-based upgrades — see Running Playbooks — Upgrades

• Ubuntu/Debian upgrades — a separate guide is available

• Windows or macOS worker upgrades — see the respective platform guides

• Elasticsearch version upgrades (e.g., 7.x → 8.x). If you are still on Elasticsearch 7.x, perform the ES upgrade separately using the Elastic documentation before running this procedure.

Architecture Recap

A typical Diskover deployment has these host groups:

In single-host deployments, all four groups run on the same machine. In multi-host deployments, each group runs on dedicated hosts. This upgrade only touches the web and worker host groups — Elasticsearch, RabbitMQ, and Kibana are left in place.

Pre-Upgrade Checklist

Complete every item before starting. Skipping a step here is the most common cause of upgrade issues.

• Current Diskover version verified — In Diskover Web, click the Gear Icon → Settings → Diskover Version, or run cat /opt/diskover/VERSION on a worker host
• Target version confirmed — Choose the exact target version (e.g., 2.5.1). It must be available in JFrog Artifactory.
• Release notes reviewed — Read the Diskover Release Notes for any version-specific migration steps or breaking changes
• All running scans completed or paused — Do not upgrade while an active scan is in progress. Check Diskover Admin → Task Panel
• Maintenance window scheduled — Diskover services will be stopped during the upgrade
• JFrog credentials confirmed — Verify your JFrog Artifactory username and access token are still valid. Contact Diskover Data if you need new credentials
• Elasticsearch cluster health is green or yellow — Run: curl -s http://localhost:9200/_cluster/health and verify "status" is not "red"
• Disk space available — At least 2 GB free on /root/ for backups and /var/www/ and /opt/ for the new packages

Prerequisites

Your environment should already meet these requirements (they were satisfied during your original v2.4+ install):

Backup Procedures

The Ansible playbook automates these backups. When upgrading manually, do them yourself before installing any new packages.

Set the date stamp once and reuse it. This matches the convention used by the Ansible backup role (/root/diskover-backups-YYYYMMDD/):

export DATE_STAMP=$(date +%Y%m%d)
mkdir -p /root/diskover-backups-${DATE_STAMP}
echo "Backups will be written to /root/diskover-backups-${DATE_STAMP}"

On the Web Host

# Create a date-stamped backup directory
mkdir -p /root/diskover-backups-${DATE_STAMP}/web-diskover-backups-${DATE_STAMP}

# Back up the Nginx site config and the existing systemd unit for diskover-admin
cp /etc/nginx/conf.d/diskover-web.conf       /root/diskover-backups-${DATE_STAMP}/web-diskover-backups-${DATE_STAMP}/diskover-web.conf
cp /usr/lib/systemd/system/diskover-admin.service /root/diskover-backups-${DATE_STAMP}/web-diskover-backups-${DATE_STAMP}/diskover-admin.service

On Each Worker Host

mkdir -p /root/diskover-backups-${DATE_STAMP}/worker-diskover-backups-${DATE_STAMP}

# Back up the diskoverd systemd unit (the encryption key lives in here)
cp /etc/systemd/system/diskoverd.service  /root/diskover-backups-${DATE_STAMP}/worker-diskover-backups-${DATE_STAMP}/diskoverd.service

Important: The Diskover Admin SQLite database under /var/www/diskover-web/ (which holds your Elasticsearch connections, RabbitMQ settings, and license) is not modified by the upgrade and is captured in the directory backup above. Keep these tarballs until you have verified the new version is healthy.

Upgrade Order

Follow this order on RHEL to avoid dependency issues:

1. JFrog repository confirmed and dnf cache refreshed (web + worker)

2. Python venv verified or created (web + worker, only if missing)

3. Diskover Admin and Diskover Web (web host)

4. Diskoverd, scanners, plugins, file actions (each worker host)

5. DISKOVER_ENCRYPT_SECRET_KEY verified on diskover-admin and each diskoverd unit file

6. Restart services and verify

All commands below assume you are logged in as root (or using sudo).

Step 1: Confirm the JFrog Repository (Web + Worker Hosts)

Diskover RPMs are distributed through JFrog Artifactory. If you used JFrog for your original install, the repo file already exists. Confirm it points to the right URL and that dnf can reach it.

1a. Inspect the Existing Repo File

cat /etc/yum.repos.d/diskover.repo

It should look like the following (your username and token will already be in place):

[diskover]
name=Diskover Repository
baseurl=https://your-jfrog-username:your-jfrog-token@artifactory.diskoverdata.com/artifactory/diskover-rpm-prod/
enabled=1
gpgcheck=0

If the file is missing or your credentials have rotated, recreate it with the correct values. Contact Diskover Data if you need a new JFrog username or token.

1b. Refresh the dnf Cache and List Available Versions

dnf clean all
dnf makecache

# Confirm the new version is available
dnf --showduplicates list available diskover-web diskover-admin diskoverd

You should see the version you intend to upgrade to in the output. If not, check that your repo URL and credentials are correct.

Tip: Repeat Step 1 on every host that will install Diskover packages — both the web host and each worker host.

Step 2: Python 3.11+ Virtual Environment (If Not Already Present)

Diskover v2.5+ uses a dedicated Python virtual environment at /opt/python-venv-diskover. If your original install was done with Ansible or a recent manual installer, this is already in place — verify it and skip ahead. If the venv is missing (older manual installs sometimes used the system Python directly), create it now.

Run these checks and steps on every host that runs diskover-admin or diskoverd — typically the web host and every worker host.

2a. Verify the venv

ls -ld /opt/python-venv-diskover
/opt/python-venv-diskover/bin/python3 -V

Expected output:

drwxr-xr-x. 5 root root 64 ... /opt/python-venv-diskover
Python 3.11.x   # or 3.12.x

If the directory exists and python3 -V reports 3.11 or higher, skip to Step 3.

2b. Install Python 3.11 (only if the venv does not exist)

The Ansible playbook prefers the system Python when it is already 3.12+; otherwise it installs Python 3.11. Use whichever is appropriate for your distro.

# RHEL/Rocky 8.x and 9.x — install Python 3.11
dnf -y install python3.11 python3.11-devel gcc

# RHEL/Rocky 10.x — system Python is already 3.12+, just install build tools
dnf -y install gcc python3-devel

2c. Create the venv

# Use python3.11 on RHEL 8/9, or python3.12 on RHEL 10
python3.11 -m venv /opt/python-venv-diskover

2d. Add the venv to the system PATH

cat > /etc/profile.d/diskover-venv.sh << 'EOF'
# Add Diskover venv to PATH for CLI usage
export PATH="/opt/python-venv-diskover/bin:$PATH"
EOF

chmod 644 /etc/profile.d/diskover-venv.sh
source /etc/profile.d/diskover-venv.sh

2e. Verify

which python3
# Expected: /opt/python-venv-diskover/bin/python3

python3 -V
# Expected: Python 3.11.x or 3.12.x

If which python3 does not return the venv path, run source /etc/profile.d/diskover-venv.sh again. New SSH sessions will pick this up automatically.

Step 3: Upgrade the Web Host

Diskover Admin and Diskover Web both live on the web host. Upgrade them together — do not split them across maintenance windows because Admin's API is what Diskover Web reads from for its configuration.

3a. Stop Diskover Admin

systemctl stop diskover-admin

Note: You do not need to stop Nginx or PHP-FPM for the package upgrade. The RPM update for diskover-web swaps in the new files under /var/www/diskover-web/ without disrupting either service. Users may briefly see Diskover Admin pages return errors while it is stopped — coordinate with stakeholders accordingly.

3b. Upgrade Diskover Admin and Diskover Web Packages

Replace 2.5.1 in the commands below with the version you are upgrading to. Pinning the version with package-VERSION mirrors what the Ansible playbook does and guarantees you get the exact release.

dnf install \
  diskover-admin-2.5.1 \
  diskover-web-2.5.1 \
  diskoverd-2.5.1 \
  "diskover-plugin-*" \
  "diskover-scanner-*" \
  "diskover-file-action-*"

dnf install <pkg>-<new-version> performs an in-place upgrade when an older version of the package is already installed. If you also installed Diskoverd on the web host (single-host deployments), include diskoverd-2.5.1 in the same command.

Note: Wrap the diskover-plugin-*, diskover-scanner-*, and diskover-file-action-* glob patterns in double quotes so the shell does not try to expand them against your local directory before dnf sees them. These globs tell dnf to refresh every Diskover plugin, scanner, and file action package that's already installed on this host. If you only want to upgrade specific ones, list them by name instead.

3c. Refresh Diskover Admin Python Dependencies

The new Diskover Admin RPM ships an updated requirements.txt. Reinstall pip packages inside the venv to pick up any new or changed dependencies:

/opt/python-venv-diskover/bin/pip3 install \
  -r /var/www/diskover-admin/etc/requirements.txt

If pip3 is not in your shell's PATH, run source /etc/profile.d/diskover-venv.sh first or call the venv's pip directly as shown above.

3d. Verify the DISKOVER_ENCRYPT_SECRET_KEY Fernet Key

Newer Diskover releases require a Fernet encryption key on the diskover-admin systemd unit. The Ansible playbook adds this automatically; the manual procedure must check for it and add it if it is missing.

Check whether the key is already present:

grep -E '^Environment="DISKOVER_ENCRYPT_SECRET_KEY=' /usr/lib/systemd/system/diskover-admin.service

• If output appears: The key is already in place. Skip to Step 3e.

• If no output appears: Add the key using the steps below.

Generate a new Fernet key (only if the key is missing):

/opt/python-venv-diskover/bin/python3 -c \
  "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

This prints a base64-encoded key. Copy it — you will reuse the same key on every worker host in Step 4d.

Add the key to the diskover-admin unit file:

Open the unit file and insert the Environment line directly after Environment=PYTHONUNBUFFERED=TRUE:

vi /usr/lib/systemd/system/diskover-admin.service

Example placement:

[Service]
User=root
Group=root
Environment=PYTHONUNBUFFERED=TRUE
Environment="DISKOVER_ENCRYPT_SECRET_KEY=paste-the-generated-key-here"
WorkingDirectory=/var/www/diskover-admin
...

Reload systemd so it picks up the change:

systemctl daemon-reload

Save the key somewhere safe. It is required on every worker host's diskoverd.service file. Anyone with the key can decrypt secrets stored in the Admin database, so treat it like any other credential.

3e. Start Web Services

systemctl start diskover-admin
systemctl status diskover-admin

Look for Active: active (running) and Application startup complete. in the output. If it fails, check journalctl -n 100 -u diskover-admin and include those logs in any support ticket.

systemctl start php-fpm
systemctl start nginx
systemctl status php-fpm nginx

3f. Verify the Web UI

Open the Diskover Web UI in a browser:

• HTTP: http://<web-host-ip>

• HTTPS: https://<your-diskover-fqdn>

The login page should load and display the new version number. If the old version is still shown, hard-refresh the browser (Ctrl+Shift+R / Cmd+Shift+R) to clear cached assets.

Step 4: Upgrade Each Worker Host

Repeat Steps 4a–4d on every worker host in your environment. If your web host is also acting as a worker (single-host deployment), run these steps on that host too — but only after completing Step 3.

4a. Stop Worker Services

systemctl stop diskoverd
systemctl stop celery

4b. Upgrade Diskoverd, Scanners, Plugins, and File Actions

Replace 2.5.1 with your target version:

dnf install \
  diskoverd-2.5.1 \
  "diskover-plugin-*" \
  "diskover-scanner-*" \
  "diskover-file-action-*"

Note: Wrap the wildcard package names in double quotes so the shell does not try to expand them locally before dnf runs. Workers do not install diskover-admin or diskover-web — those packages belong on the web host only.

4c. Refresh Diskoverd Python Dependencies

/opt/python-venv-diskover/bin/pip3 install \
  -r /opt/diskover/requirements.txt

4d. Verify the DISKOVER_ENCRYPT_SECRET_KEY on Each Worker

The worker's diskoverd service file lives at /etc/systemd/system/diskoverd.service and must contain the same Fernet key that lives on the diskover-admin service file on the web host. Without a matching key, Diskoverd cannot decrypt the credentials it pulls from Diskover Admin.

Check whether the key is already present:

grep -E '^Environment="DISKOVER_ENCRYPT_SECRET_KEY=' /etc/systemd/system/diskoverd.service

• If the line is present and matches the key on the web host: Skip to Step 4e.

• If the line is missing: Continue below.

Retrieve the key from the web host (run this on the web host):

grep -oP 'DISKOVER_ENCRYPT_SECRET_KEY=\K[^"]*' \
  /usr/lib/systemd/system/diskover-admin.service

Copy the output — that is your shared key.

Add the key to the worker's diskoverd unit file:

vi /etc/systemd/system/diskoverd.service

Insert the Environment line directly after User=root (mirroring how the playbook places it):

[Service]
User=root
Environment="DISKOVER_ENCRYPT_SECRET_KEY=paste-the-key-from-web-host-here"
ExecStart=/opt/python-venv-diskover/bin/python3 /opt/diskover/diskoverd.py
...

Reload systemd:

systemctl daemon-reload

4e. Start Worker Services

systemctl start diskoverd
systemctl status diskoverd

Diskoverd should report Active: active (running). If it fails, run journalctl -fu diskoverd and check for license, encryption key, or RabbitMQ connection errors.

systemctl start celery
systemctl status celery

If Celery fails to start, the most common cause is that the RabbitMQ host or credentials configured in Diskover Admin do not match the running RabbitMQ broker. Check /var/log/celery/ for details.

Step 5: Post-Upgrade Verification

Run through this checklist to confirm the upgrade succeeded.

Rollback Procedures

If the upgrade introduces a critical issue, roll back to the previous version using the tarballs created during the Backup Procedures step.

When to Rollback

• Critical functionality (Web UI, scanning, file actions) is broken after the upgrade

• Services repeatedly fail to start and standard troubleshooting does not resolve the issue

• Data corruption is detected in Elasticsearch indices that traces to the upgrade

Rollback Steps

1. Stop all Diskover services on the affected hosts:

   # Web host
   systemctl stop diskover-admin nginx php-fpm
   
   # Each worker host
   systemctl stop diskoverd celery

2. Re-install the previous Diskover version. Replace 2.x.x with whatever version you were on before the upgrade (for example, 2.5.0):

   # Web host
   dnf install \
     diskover-admin-2.x.x \
     diskover-web-2.x.x \
     "diskover-plugin-*" \
     "diskover-scanner-*" \
     "diskover-file-action-*" \
   
   # Each worker host
   dnf install \
     diskoverd-2.x.x \
     "diskover-plugin-*" \
     "diskover-scanner-*" \
     "diskover-file-action-*" \

3. Restore configuration files from the backup tarballs if any of them changed during the upgrade. Replace YYYYMMDD with your backup's date stamp:

   # Example — restore the web host nginx config and diskover-admin service file
   cp /tmp/web-diskover-backups-YYYYMMDD/diskover-web.conf \
      /etc/nginx/conf.d/diskover-web.conf
   cp /tmp/web-diskover-backups-YYYYMMDD/diskover-admin.service \
      /usr/lib/systemd/system/diskover-admin.service
   
   systemctl daemon-reload

   For workers, restore diskoverd.service and (if needed) /root/.config/diskoverd/config.yaml from the worker tarball.

4. Reinstall the Python pip dependencies for the previous version so the venv matches the older code:

   # Web host
   /opt/python-venv-diskover/bin/pip3 install -r /var/www/diskover-admin/etc/requirements.txt
   
   # Each worker host
   /opt/python-venv-diskover/bin/pip3 install -r /opt/diskover/requirements.txt

5. Start services in the original order:

   # Web host
   systemctl start diskover-admin php-fpm nginx
   
   # Each worker host
   systemctl start diskoverd celery

6. Verify the Diskover Web UI version matches the rolled-back release and that workers register in the Task Panel.

Service Management Reference

Troubleshooting

Log File Locations

Support

If you encounter issues during the upgrade that you cannot resolve using this guide:

• Support Portal: https://support.diskoverdata.com

• Help Center: https://support.diskoverdata.com/hc/en-us

When submitting a support ticket for upgrade issues, please include:

• Previous Diskover version and target version

• Target OS and version (cat /etc/os-release)

• The upgrade step where the issue occurred

• Service logs (journalctl -u diskover-admin, journalctl -u diskoverd, /var/log/celery/)

• Output of the failing dnf install or pip install command, if applicable

See Also

• Running Playbooks — Upgrades — Ansible-driven equivalent of this procedure

• Diskover 2.2.x to 2.5.x+ Upgrade Process (RHEL) — Use this if you are upgrading from a v2.2.x or older deployment that does not yet have Diskover Admin

• Manual Installation Guide — Full Stack (RHEL/Rocky Linux) — For fresh installations

• Manually Upgrading PHP — If you also need to upgrade PHP as part of this maintenance window

• Changing Python Versions — If you need to move from one Python minor version to another inside the venv