Fix Mideye Installation & Upgrade Issues (Linux/Windows)

This guide addresses common problems encountered during Mideye Server installation and upgrades, particularly the critical timing issue where the service starts before all configuration files are properly in place.

Overview

The most common installation and upgrade issue occurs when the service starts too quickly — before configuration files are fully copied or database migrations complete. This results in startup failures that require manual intervention.

Common Issues

Service Starts Before Files Are Ready

Problem: After installing or upgrading the Mideye Server package, the service starts immediately but fails because configuration files aren’t ready.

Symptoms:

Service fails to start after package installation/upgrade
Error messages about missing configuration files
Service status shows “failed” or “activating”

Solution:

Check service status:

Linux:

systemctl status mideyeserver6
journalctl -u mideyeserver6 -n 50 --no-pager

Windows:

Get-Service MideyeServer6
Get-Content "C:\Program Files\Mideye Server\log\mideyeserver.log" -Tail 50

Verify configuration files exist:

Linux:

ls -la /opt/mideyeserver6/config/application-prod.yml
ls -la /opt/mideyeserver6/config/logback.xml
ls -la /opt/mideyeserver6/config/keystore.p12

Windows:

Test-Path "C:\Program Files\Mideye Server\config\application-prod.yml"
Test-Path "C:\Program Files\Mideye Server\config\keystore.p12"

Fix file permissions (Linux):

sudo chown mideye:mideye /opt/mideyeserver6/config/*
sudo chmod 660 /opt/mideyeserver6/config/application-prod.yml
sudo chmod 660 /opt/mideyeserver6/config/logback.xml
sudo chmod 660 /opt/mideyeserver6/config/keystore.p12

Manually restart the service:

Linux:
Terminal window
```
sudo systemctl restart mideyeserver6
```
Windows:
Terminal window
```
Restart-Service MideyeServer6
```

Prevention:

After upgrades, always wait 10–15 seconds before checking service status
Monitor logs during first startup after upgrade

Missing or Inaccessible Configuration Files

Problem: Service fails to start with errors about missing configuration files.

Root Causes:

Configuration files not preserved during upgrade
Files exist but have wrong permissions
Incorrect file paths

Required files:

application-prod.yml — Main production configuration
logback.xml — Logging configuration
keystore.p12 — TLS/SSL keystore

Solution:

Linux:

# List all config files
ls -la /opt/mideyeserver6/config/

# Fix ownership and permissions
sudo chown -R mideye:mideye /opt/mideyeserver6/config
sudo chmod 660 /opt/mideyeserver6/config/*.yml
sudo chmod 660 /opt/mideyeserver6/config/*.xml
sudo chmod 660 /opt/mideyeserver6/config/*.p12

# If keystore is missing, regenerate
sudo /opt/mideyeserver6/bin/generate-selfsigned-tls-keystore.sh
sudo chown mideye:mideye /opt/mideyeserver6/config/keystore.p12
sudo chmod 660 /opt/mideyeserver6/config/keystore.p12

Database Not Ready During Startup

Problem: Service starts but fails because the database isn’t ready for connections.

Symptoms:

“Communications link failure” in logs
“Connection refused” to database
Service enters failed state after several minutes

Diagnostic Steps:

Linux:

# Check database is running
systemctl status mariadb

# Test database connection
mysql -h localhost -u root -p mideyeserver

Solution:

Start the database service before Mideye Server
Ensure the database service is configured to start on boot
Restart Mideye Server after the database is running

See Database Issues for detailed database troubleshooting.

Database Migration Failures

Problem: Database schema migrations fail during startup, leaving the database in an inconsistent state.

Symptoms:

“Waiting for changelog lock” messages in logs
“Validation Failed” errors
Service fails to start

Solution:

Check for stuck migration lock:
```
SELECT * FROM DATABASECHANGELOGLOCK;
```
If lock is stuck (LOCKED=1 with no service running), release it:
```
UPDATE DATABASECHANGELOGLOCK SET LOCKED=0, LOCKGRANTED=NULL, LOCKEDBY=NULL;
```
Only release the lock if you are certain no migration is actually running.
Restart Mideye Server

See Database Issues for more details.

File Permission Errors

Problem: Service can’t read configuration files or write to log directories.

Symptoms:

“Permission denied” errors in logs
Service fails to start
Unable to write log files

Solution (Linux):

# Fix ownership recursively
sudo chown -R mideye:mideye /opt/mideyeserver6

# Set correct permissions on directories
sudo find /opt/mideyeserver6 -type d -exec chmod 750 {} +

# Set correct permissions on config files
sudo chmod 660 /opt/mideyeserver6/config/application-prod.yml
sudo chmod 660 /opt/mideyeserver6/config/logback.xml
sudo chmod 660 /opt/mideyeserver6/config/keystore.p12

# Ensure log directory is writable
sudo mkdir -p /opt/mideyeserver6/log
sudo chown mideye:mideye /opt/mideyeserver6/log
sudo chmod 750 /opt/mideyeserver6/log

# If using SELinux
sudo restorecon -Rv /opt/mideyeserver6

Self-Signed Certificate Generation Fails

Problem: During installation, the automatic generation of the self-signed TLS certificate fails.

Symptoms:

No keystore.p12 file created
Service fails to start with keystore-related errors

Solution (Linux):

# Manually run keystore generation
sudo /opt/mideyeserver6/bin/generate-selfsigned-tls-keystore.sh

# Set permissions
sudo chown mideye:mideye /opt/mideyeserver6/config/keystore.p12
sudo chmod 660 /opt/mideyeserver6/config/keystore.p12

# Restart service
sudo systemctl restart mideyeserver6

Alternatively, once the service is accessible, use the Certificate Management page in the web interface to manage certificates.

Post-Installation Verification

After installing or upgrading, verify the installation is successful:

1. Check Service Status

Linux:

systemctl status mideyeserver6

Windows:

Get-Service MideyeServer6

Expected: Service is running.

2. Verify Service is Listening

Linux:

ss -tlnp | grep -E "8080|1812|1813"

Windows:

Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue

Expected: Service listening on configured ports (typically 8080, 1812, 1813).

3. Check Application Logs

Open the Log Files page in the web interface and look for:

“Started MideyeServerApp” message
No ERROR messages
Successful database connection messages

4. Access Web Interface

Open browser to https://your-server:8080 — you should see the Mideye Server login page.

5. Test Authentication

Authenticate a test user through RADIUS to verify full functionality.

Upgrade Best Practices

To minimize upgrade issues:

Back up before upgrading:

Linux:

# Backup configuration
sudo tar -czf /tmp/mideyeserver-config-backup.tar.gz /opt/mideyeserver6/config

# Backup database
mysqldump -u root -p mideyeserver > /tmp/mideyeserver-db-backup.sql

Windows:

# Backup configuration folder
Copy-Item "C:\Program Files\Mideye Server\config" -Destination "C:\backups\mideyeserver-config" -Recurse

Stop service before upgrade:

Linux:
Terminal window
```
sudo systemctl stop mideyeserver6
```
Windows:
Terminal window
```
Stop-Service MideyeServer6
```
Verify database is running before starting the upgrade
Perform upgrade using your package manager
Wait 10–15 seconds after upgrade completes
Check service status and monitor logs during first startup
Verify web interface is accessible
Test authentication functionality

Emergency Rollback

If an upgrade fails and the service won’t start:

Stop the service
Restore configuration from backup
Restore database from backup
Downgrade the package to the previous version
Start the service
Verify functionality

Getting Help

If installation or upgrade issues persist, contact Mideye Support with:

Mideye Server version
Operating system and version
Log files (from Log Files page or exported)
Description of what was being done when the issue occurred
Configuration files (passwords removed)