Installation Issues

Troubleshoot common problems during platform installation and setup.

Backend Won’t Start

Symptom

Backend container exits immediately or fails to start.

Common Causes

  1. Metadata database not accessible

Check logs:

docker compose logs backend | grep -i error

Solution: Verify PostgreSQL is running and accessible.

  1. Database credentials incorrect

Solution: Check environment variables:

echo $SPRING_DATASOURCE_URL
echo $SPRING_DATASOURCE_USERNAME

  1. Port already in use

Solution: Change port or stop conflicting service:

# Change port in docker-compose.yml
ports:
  - "8081:8080"  # Use 8081 instead

Database Migration Fails

Symptom

Error messages about schema migrations or Liquibase.

Solution

  1. Clean database and restart:

# Remove existing data
docker compose down -v

# Restart
docker compose up -d

  1. Manual migration check:

-- Connect to metadata database
SELECT * FROM databasechangelog;

Cannot Access Web UI

Symptom

Browser shows "Connection refused" or "Unable to connect".

Solutions

  1. Check backend is running:

docker compose ps backend

  1. Verify port mapping:

curl http://localhost:8080/actuator/health

  1. Check firewall:

# Test from server
curl -I http://localhost:8080

# Check firewall rules
sudo iptables -L

Agent Won’t Connect

Symptom

Agent container starts but doesn’t appear in backend UI.

Solutions

  1. Check BACKEND_URL:

docker compose logs agent | grep BACKEND_URL

  1. Verify network connectivity:

docker compose exec agent curl http://backend:8080/actuator/health

  1. Check backend logs:

docker compose logs backend | grep -i agent

Insufficient Memory

Symptom

"OutOfMemoryError" in logs.

Solution

Increase memory allocation:

# docker-compose.yml
services:
  backend:
    environment:
      JAVA_OPTS: "-Xmx4g"  # Increase to 4GB

See Also