Troubleshooting — Diskover on Debian/Ubuntu

Overview

Ubuntu hosts can run the full Diskover stack or act as dedicated indexer nodes. This guide covers the most common issues across all Diskover services on Ubuntu.

Full stack services:

Indexer-only nodes (remote workers) run only celery and diskoverd.

Quick Status Check

PHP_FPM=$(systemctl list-units --type=service | grep -o 'php[0-9.]*-fpm' | head -1)
for svc in elasticsearch nginx $PHP_FPM rabbitmq-server celery diskover-admin diskoverd; do
  printf "%-20s %s\n" "$svc" "$(systemctl is-active $svc 2>/dev/null || echo 'not-found')"
done

Note: The PHP-FPM service name includes the version number (e.g., php8.2-fpm). Adjust commands below to match the version installed on your system.

Service Startup Order

Services have dependencies. The correct startup sequence is:

1. elasticsearch

2. rabbitmq-server

3. diskover-admin

4. nginx

5. php<version>-fpm

6. celery

7. diskoverd

Always confirm earlier services are healthy before investigating later ones.

Log Locations Reference

Troubleshooting

Diskover Web UI Not Loading

Check nginx:

sudo systemctl status nginx
sudo tail -20 /var/log/nginx/error.log

Check PHP-FPM:

sudo systemctl status php8.2-fpm
sudo tail -50 /var/log/nginx/error.log | grep fastcgi

If nginx is up but returns a 502 on /diskover_admin routes, diskover-admin is likely down — see below.

Check file ownership — the nginx worker user on Ubuntu is www-data:

ls -la /var/www/diskover-web/public
sudo chown -R www-data:www-data /var/www/diskover-web

diskover-admin Not Responding (502 on /diskover_admin)

sudo systemctl status diskover-admin
sudo journalctl -u diskover-admin -n 100 --no-pager

Check the Unix socket:

ls -la /var/www/diskover-admin/run/diskover-admin.sock

If missing, start diskover-admin:

sudo systemctl start diskover-admin

If the socket exists but 502 persists, fix permissions:

sudo chown www-data:www-data /var/www/diskover-admin/run/diskover-admin.sock
sudo chmod 777 /var/www/diskover-admin/run/diskover-admin.sock

Common startup failure causes:

• SQLite database not accessible: ls -la /var/www/diskover-web/diskoverdb.sqlite3

• Task Worker not installed at /opt/diskover: ls /opt/diskover/models/

• Python dependency missing — test manually:

  cd /var/www/diskover-admin && uvicorn --interface wsgi --workers 1 wsgi:app
  

Tasks Not Running / Crawls Not Starting

1. Confirm RabbitMQ is running:

sudo systemctl status rabbitmq-server
sudo rabbitmqctl list_queues name messages consumers

A queue with messages > 0 and consumers = 0 means the Celery worker for that hostname is down.

2. Confirm the Celery worker is consuming:

sudo systemctl status celery
/opt/python-venv-diskover/bin/celery -A diskover_celery.worker inspect active_queues

The worker should be consuming index.<hostname> and fileactions.<hostname>.

3. Confirm diskoverd is running:

sudo systemctl status diskoverd
sudo tail -50 /var/log/diskover/diskoverd.log

4. Check worker name consistency:

hostname
sudo rabbitmqctl list_queues name consumers

The queue names must match the worker name. See the diskoverd doc if they don't.

Crawl Task Fails

sudo tail -100 /var/log/diskover/diskoverd_subproc.log

For more detail, set log level to DEBUG in Diskover Admin > Configuration > DiskoverD, restart diskoverd, and retry.

Common causes:

• Elasticsearch unreachable: curl -s http://<es-host>:9200/_cluster/health

• Path not accessible to the user running diskoverd

• NFS/CIFS mount failure:

  showmount -e <nfs-server>   # NFS
  mount | grep diskover
  

  Install packages if missing: sudo apt install nfs-common cifs-utils Or start diskoverd with --assumemountingenabled to skip mount capability checks

Elasticsearch Issues

Cluster health:

curl -s http://localhost:9200/_cluster/health?pretty

yellow is normal for single-node clusters. red means a primary shard is missing — check the log:

sudo tail -100 /var/log/elasticsearch/diskover.log

Disk space — most common cause of ES going read-only:

df -h /var/lib/elasticsearch

Elasticsearch stops writing at 90% disk usage. After freeing space, clear the watermark block:

curl -X PUT "http://localhost:9200/*/_settings" \
  -H 'Content-Type: application/json' \
  -d '{"index.blocks.read_only_allow_delete": null}'

See the Elasticsearch doc for more.

Firewall — Ports Reference

sudo ufw status
sudo ufw allow <port>/tcp

Disk Space / Log Rotation

df -h /var/log /var/lib/elasticsearch /opt/diskover

Log rotation is configurable in Diskover Admin > Configuration > Diskover > Logging. For Elasticsearch index cleanup, see the Kibana doc.

Reinstalling Python Dependencies

If Diskover services fail to start with ModuleNotFoundError or similar import errors, reinstalling the Python dependencies can resolve the issue. This is also required after a Diskover upgrade that introduces new package requirements.

Diskover on Ubuntu uses a virtual environment at /opt/python-venv-diskover/:

# Reinstall all dependencies
sudo /opt/python-venv-diskover/bin/python3 -m pip install -r /opt/diskover/requirements.txt

# For diskover-admin
sudo /opt/python-venv-diskover/bin/python3 -m pip install -r /var/www/diskover-admin/etc/requirements.txt

After reinstalling, restart the affected services:

sudo systemctl restart diskover-admin diskoverd celery

License Failure

An expired or missing license causes diskoverd and Celery to exit at startup:

sudo tail -50 /var/log/diskover/diskoverd.log
sudo tail -50 /opt/diskover/diskover_celery/log/<nodename>.log

Contact Diskover support to obtain or renew a license.