Troubleshoot

Common Issues

Uploads or AirMapper Surveys Stay Stuck on Processing

Uploaded files never finish processing, and no error appears anywhere in the interface. The symptom is distinctive: the web interface works normally when you browse to it from the server itself, and small files fail in exactly the same way as large ones.

Cause – The host was set to 127.0.0.1 or localhost during setup. That address is also used as the internal storage endpoint, so the component that processes uploads looks for the file on itself, never finds it, and retries indefinitely instead of reporting a failure.

Fix – Rerun the host step with the server's real IP address or DNS hostname:

Ubuntu: sudo ./ubuntu-start.sh host

RHEL: ./rhel-start.sh host

Then browse to https://<that address> rather than to 127.0.0.1. Items that were already stuck should finish processing shortly afterward. Re-upload anything that does not.

Script Locations and Names

The start script is the only script at the root of the installation directory, and the only one with an operating system prefix: sudo ./ubuntu-start.sh on Ubuntu, ./rhel-start.sh on RHEL. Using the wrong prefix or privilege level results in an error.

All other scripts are in the toolkit/ folder and have plain names with no prefix. Run them with sudo on Ubuntu and without sudo on RHEL.

See Script Naming and Usage.

Script Not Found

The utility scripts moved into the toolkit/ folder, so a command such as ./backup.sh now fails. Add the folder to the path:

Ubuntu: sudo ./toolkit/backup.sh

RHEL: ./toolkit/backup.sh

Setup Failure

  • If you experience permissions errors with Ubuntu, run as sudo.

  • If using Ubuntu, verify that you have Docker Compose v2. Check with the docker compose version command, and expect a 2.x version number.

    NOTE: Note the space in docker compose. The legacy standalone docker-compose binary is version 1 and is no longer used. If you are upgrading from an older installation, the v2 plugin is installed for you automatically.

  • If using RHEL, ensure that commands are run without sudo. Link-Live Private uses rootless Podman on RHEL, and using sudo will cause setup or permission failures.

Required Operating System Packages Are Not Installed

On a minimal Ubuntu installation, a package the installer needs may be missing, and an offline server cannot download it. The installer checks for this before making any changes and names exactly which packages are missing.

Install the named packages from your Ubuntu installation media or from your internal mirror, then run the start script again.

A related message names conflicting packages that must be removed first. Remove the named packages, then run the start script again.

Port 443 Is Already in Use

The installer checks port 443 before starting and stops with an error naming the process that is holding the port. Stop that process, commonly another web server, then run the start script again.

https Works but http Does Not Connect

This is expected. Only port 443 is served: there is no HTTP listener and no redirect from http:// to https://. Browse to https:// explicitly.

Tester Upload Failure

  • On your tester, ensure you are using https:// in the Link-Live app's Link-Live Private Settings > Deployment Name (URL).

  • Ensure you do not have www. in your host name.

  • Run nslookup Link-Live-Private.mycompany.com (for example) on your DNS name and verify that the name is exactly the same as your host value.

Containers Stop When I Log Out, or Do Not Return After a Reboot (RHEL)

On RHEL this is normally handled for you: the start script enables session lingering and registers the linklive.service systemd user service at the end of every install and update.

Cause – The boot service did not register, most often because the bundle directory was moved after installation, or because the account running the install could not obtain sudo.

Fix – From inside the installation directory, run:

./toolkit/register-service.sh

Verify with:

loginctl show-user $USER --property=Linger

systemctl --user is-enabled linklive.service

I Cannot Reach the Server from Another Machine (RHEL)

Cause – The firewall is blocking port 443. The installer opens it, but a hardened or re-imaged host may have had the rule removed.

Fix – Check the rule with:

sudo firewall-cmd --query-port=443/tcp

Logging

Run the export-logs.sh script in the toolkit folder to generate logs:

Ubuntu: sudo ./toolkit/export-logs.sh

RHEL: ./toolkit/export-logs.sh

The log archive is named link-live-private-logs_<timestamp>.tar.xz.

Resetting Everything

CAUTION! This process will remove everything related to Docker/Podman and Link-Live Private. You will lose all your Link-Live Private data and state!

Docker

Ensure you do not need any data and that only Link-Live Private is using Docker on your machine before running these commands.

Run the following commands:

sudo docker stop $(sudo docker ps -aq)

sudo docker rm $(sudo docker ps -aq)

sudo docker rmi -f $(sudo docker images -aq)

sudo docker volume rm $(sudo docker volume ls -q)

sudo docker network rm $(sudo docker network ls -q)

RHEL

Ensure that you do not need any existing data and that Link-Live Private is the only application using Podman containers and volumes on this machine before proceeding.

Run the following commands:

systemctl --user disable --now linklive.service

podman stop $(podman ps -aq)

podman rm $(podman ps -aq)

podman rmi -f $(podman images -aq)

podman volume rm $(podman volume ls -q)

podman network rm $(podman network ls -q)