Skip to content

Troubleshooting

This page provides solutions to common issues you may encounter during installation and operation of ApiFort.

Common Issues

Issue Solution
Environment variable changes in .env are not applied automatically Update .env and run docker compose up -d to apply changes.
Container exits immediately after starting Check logs with docker compose logs <service-name> for error messages.
Cannot access the web interface Verify firewall rules allow traffic on ports 80/443. Check that the router container is running.
Keycloak authentication fails Ensure KC_HOSTNAME in docker-compose.yml matches your actual hostname.

Troubleshooting by Category

1. Container Issues

Container Exited Immediately

Symptoms: Container shows "Exited" status shortly after starting.

Solutions:

  • Use docker compose logs <container_name> to check for errors in the logs
  • Verify that all required environment variables are correctly configured in the docker-compose.yml file
  • Check if the container has sufficient resources allocated
  • Ensure the container image was loaded correctly

Example:

Bash
# Check why backend container exited
docker compose logs backend

# Check container status
docker compose ps

Container Restarts Frequently

Symptoms: Container keeps restarting repeatedly.

Solutions:

  • Check system resources (CPU, memory, disk space) using docker stats
  • Monitor individual container resource usage: docker stats <container_name>
  • Review container logs for errors before restart
  • Verify resource limits in docker-compose.yml are appropriate

2. Network and Connectivity Issues

Port Conflicts

Symptoms: Container fails to start with port binding errors.

Solutions:

  • Ensure that the ports specified in the docker-compose.yml file are not already in use by another service
  • Check port usage:
    • Linux: netstat -tulpn | grep <port>
    • Windows: netstat -an | findstr <port>
  • Modify port mappings in docker-compose.yml if needed
Database Connection Issues

Symptoms: Application cannot connect to the database.

Solutions:

  • Ensure that the database container is running and accessible
  • Verify the credentials in the docker-compose.yml file are correct
  • Check that the network configuration allows communication between containers
  • Test database connectivity:
    Bash
    docker exec -it postgresql psql -U appuser -d apifort
Kafka Connection Issues

Symptoms: Services cannot connect to Kafka, or Kafka is unreachable.

Solutions:

  • Verify Kafka is running: docker compose ps kafka
  • Check Kafka logs: docker compose logs kafka
  • Test Kafka connectivity from inside the network:
    Bash
    docker exec -it kafka /opt/kafka/bin/kafka-topics.sh --list --bootstrap-server kafka:9092
  • Test external Kafka access:
    Bash
    docker exec -it kafka /opt/kafka/bin/kafka-topics.sh --list --bootstrap-server YOUR_PUBLIC_IP:9094
  • Verify KAFKA_ADVERTISED_LISTENERS is correctly configured with your server's IP

3. Configuration Issues

Hostname Resolution Issues

Symptoms: Cannot access application via domain name, or SSL errors occur.

Solutions:

  • Verify your domain DNS settings point to the correct IP address
  • Test domain resolution: nslookup your-domain.com
  • Ensure firewall rules allow traffic on required ports (80, 443, 9094, 9095)
  • Verify KC_HOSTNAME, PUBLIC_HOST, and ALLOWED_HOSTS are correctly set
Incorrect Configuration

Symptoms: Application behavior is unexpected or services fail to communicate.

Solutions:

  • Ensure that all parameters in the docker-compose.yml file are correctly configured
  • Validate YAML syntax: docker compose config
  • Review the Configuration page for required parameters
  • Check that hostnames match between services (e.g., Keycloak URL in backend matches actual Keycloak hostname)

4. Resource Issues

Resource Limitations

Symptoms: Containers are slow or unresponsive, frequent restarts.

Solutions:

  • Check system resources (CPU, memory, disk space) using docker stats
  • Monitor individual container resource usage: docker stats <container_name>
  • Review system resource usage:
    Bash
    df -h   # Disk usage
free -h # Memory usage
top     # CPU usage
  • Ensure your system meets the System Requirements
  • Consider upgrading hardware if consistently hitting resource limits
Disk Space Issues

Symptoms: Containers fail to start or stop working after running for some time.

Solutions:

  • Check available disk space: df -h
  • Clean up Docker resources:
    Bash
    # Remove unused containers, networks, and images
docker system prune -a

# Remove specific stopped containers
docker container prune

# Remove unused volumes (WARNING: this deletes data)
docker volume prune
  • Set up log rotation to prevent log files from consuming all disk space
  • Monitor disk usage regularly

5. Performance Issues

Slow Image Loading

Symptoms: ./config.sh load_images takes more than 5 minutes.

Solutions:

  • Verify your CPU meets the minimum requirements (see System Requirements)
  • Check system resource usage during loading
  • Ensure SSD storage is being used
  • Close other resource-intensive applications during loading
Slow Application Response

Symptoms: Web interface or API responses are slow.

Solutions:

  • Check container resource usage: docker stats
  • Monitor response times and identify slow queries
  • Adjust container resource limits based on usage patterns
  • Consider implementing caching strategies
  • Perform regular database maintenance and optimization
  • Review traffic patterns and ensure hardware matches the load

Diagnostic Commands

Essential Monitoring Commands

Bash
# Check container status
docker compose ps

# Follow all logs in real-time
docker compose logs -f

# View specific service logs
docker compose logs <service>

# Monitor resource usage
docker stats

# Restart specific service
docker compose restart <service>

# Full restart
docker compose down && docker compose up -d

Troubleshooting Commands

Bash
# Validate docker-compose.yml configuration
docker compose config

# Access container shell
docker exec -it <container> bash

# Detailed container information
docker inspect <container>

# Check port usage (Linux)
netstat -tulpn | grep <port>

# Check Docker networks
docker network ls
docker network inspect apifort-network

# Test connectivity between containers
docker exec -it backend ping postgresql
docker exec -it backend ping kafka

Health Check Commands

Bash
# Backend health check
curl -f http://localhost:9050/api/actuator/health

# Keycloak health check
curl -f http://localhost:8080/auth/health/ready

# Database health check
docker exec -it postgresql psql -U appuser -tAc 'select 1' -d apifort

Getting Help

If you continue to experience issues after trying these troubleshooting steps:

  1. Collect diagnostic information:

    Bash
    # Gather all relevant logs
docker compose logs > apifort-logs.txt

# Get container status
docker compose ps > container-status.txt

# Get system information
docker info > docker-info.txt

  2. Contact ApiFort Support with:

    • Description of the issue
    • Log files collected above
    • Your docker-compose.yml (remove sensitive information like passwords)
    • System specifications
    • Steps you've already tried

Prevention Best Practices

Regular Maintenance

  • Daily: Check container status using docker compose ps
  • Weekly: Review container logs for errors or warnings
  • Monthly: Monitor resource usage trends and optimize if necessary

Backup Strategy

  • Regularly backup your docker-compose.yml configuration
  • Backup database data volumes
  • Document any custom configuration changes

Monitoring

  • Set up log rotation to prevent disk space issues
  • Configure alerts for container failures
  • Monitor resource usage thresholds
  • Implement health check endpoints monitoring

Security

  • Regularly update container images
  • Monitor access logs for suspicious activity
  • Ensure proper firewall configuration
  • Use strong passwords and rotate them regularly