Troubleshooting Guide

Step-by-step diagnostic procedures and solutions for common deployment, database, gateway, and desktop client issues.

Docker Service Health Checks

If containers fail to start or exit unexpectedly, inspect container status:

cd /opt/allsafex
docker compose ps -a

If a container is in a restart loop (e.g. Restarting (1)), inspect its stdout/stderr:

# View recent container logs
docker compose logs --tail=100 core
docker compose logs --tail=100 gateway

Database Connection Timeouts

Symptom: Core logs display psycopg2.OperationalError: could not connect to server.

Solution:

1. Verify PostgreSQL is running: docker compose ps postgres
2. Confirm credentials in .env match the PostgreSQL initialization password.
3. Check if PostgreSQL disk storage is full: df -h.

Port 2222 SSH Connection Refused

Symptom: Running ssh -p 2222 user@server returns Connection refused or times out.

Solution:

1. Verify the Gateway container is running: docker compose ps gateway
2. Check if another service is conflicting on port 2222:

   sudo lsof -i :2222
   # or
   sudo ss -tulpn | grep 2222

3. Ensure your firewall allows incoming traffic on port 2222:

   sudo ufw status
   sudo ufw allow 2222/tcp

Desktop Client Connectivity Issues

Symptom: The AllSafeX Desktop app displays "Unable to reach AllSafeX server" or SSL handshake error.

Solution:

• Ensure you included the correct scheme in the server URL (http:// or https://).
• If using self-signed certificates, ensure your workstation trusts the Root CA or configure testing mode in settings.
• Verify workstation proxy settings do not intercept internal domain traffic.

Diagnostic Log Inspection

Collect full diagnostic logs for support assistance:

# Collect diagnostic bundle
cd /opt/allsafex
docker compose logs > /tmp/allsafex-diagnostic.log