Troubleshooting — Diskover-Admin

Overview

diskover-admin is the Python-based administrative backend for the Diskover platform. It serves two roles:

1. Admin UI — configuration management, task management, file actions, and system setup, accessible at https://<host>/diskover_admin/

2. REST API — a programmatic interface for volumes, search, and configuration, with Swagger documentation at https://<host>/diskover_admin/api/

It runs as a Python ASGI application (Flask via uvicorn) behind nginx, communicating over a Unix socket. It imports shared configuration models from the Diskoverd service (/opt/diskover) and reads/writes to the shared SQLite database.

Service Management

RHEL / CentOS / Rocky Linux and Ubuntu

Commands are identical across distributions:

# Start
sudo systemctl start diskover-admin

# Stop
sudo systemctl stop diskover-admin

# Restart
sudo systemctl restart diskover-admin

# Status
sudo systemctl status diskover-admin

# Enable on boot
sudo systemctl enable diskover-admin

Note: diskover-admin must be running before nginx can proxy /diskover_admin traffic. If diskover-admin is down, nginx will return a 502 error on those routes.

Configuration

All configuration is managed through the Diskover Admin UI at /diskover_admin/config/. Changes made in the UI take effect immediately without a service restart. The only exceptions are:

• Configuration > System > API

• Configuration > Diskoverd > nameOfWorkerConfig

Diskover Task Worker Dependency

diskover-admin imports models and utilities from the Diskoverd service at runtime. The Task Worker must be installed at /opt/diskover and its dependencies must be on the Python path. If the Task Worker is missing or misconfigured, diskover-admin will fail to start.

Log Locations

# Tail application logs
sudo tail -f /var/log/diskover/diskover-admin.log

# Check systemd journal for startup issues
sudo journalctl -u diskover-admin -n 100 --no-pager

Key Routes

Common Operations

Verify diskover-admin Is Responding

curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/diskover_admin/

Expected: 200 or 302 (redirect to login). A 502 means nginx is running but diskover-admin is not.

Check the Unix Socket

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

The socket should be owned by nginx:nginx with permissions srwxrwxrwx. If it's missing, diskover-admin is not running.

Reload After Config Changes

Most configuration changes made through the Diskover Admin UI take effect immediately without a restart. Changes that specifically alter the way the service runs may require a service restart:

sudo systemctl restart diskover-admin

Add a File Action

1. Install the file action package on the server

2. Restart diskover-admin: sudo systemctl restart diskover-admin

3. The file action will appear under /diskover_admin/config

Troubleshooting

diskover-admin Fails to Start

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

Common causes:

• SQLite database not accessible — verify the database file exists:

  ls -la /var/www/diskover-web/diskoverdb.sqlite3
  

• Task Worker not found — verify /opt/diskover exists and contains the required modules:

  ls /opt/diskover/models/
  

• Python dependency missing — run the uvicorn command manually to see the full error:

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

502 on /diskover_admin Routes

nginx is running but cannot reach the diskover-admin socket.

1. Check diskover-admin is running: sudo systemctl status diskover-admin

2. Check the socket exists and has correct permissions:

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

3. If socket exists but 502 persists, fix permissions:

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

Session Expires Immediately / Login Loop

• Ensure the sessions directory is writable:

  ls -la /var/www/diskover-admin/instance/sessions/
  

Configuration Changes Not Saving

• Check disk space — a full disk will silently prevent SQLite writes

• Check file permissions on diskoverdb.sqlite3:

  ls -la /var/www/diskover-web/diskoverdb.sqlite3
  

  The file must be writable by the user running diskover-admin (default: root)

• Check the journal for SQLite errors:

  sudo journalctl -u diskover-admin --since "5 minutes ago"
  

File Actions and Plugins Not Appearing in the UI

1. Confirm the package is installed and importable:

   cd /var/www/diskover-admin
   python3 -c "import <fileaction_module_name>"
   

2. Restart diskover-admin and check the journal for import errors