Ontopic Docs

# Troubleshooting

# Configuration issues

# Docker-based installations

  • Check that all required secret files exist in the SECRETS_ROOT_DIR
  • Verify port conflicts if services fail to start
  • Review logs with docker-compose logs [service-name] for specific issues
  • Ensure proper file permissions on secret files (readable by Docker)

# Windows Desktop

  • File Permissions: Ensure the desktop application has proper permissions to access local files
  • License File: Confirm the license file exists in the secrets directory or default application folder
  • Antivirus Software: Ensure antivirus software is not blocking the application or its components
  • Application Logs: Check application logs in the default logs directory if services fail to start
  • Electron issues: For Electron app issues, enable developer tools with START_WITH_DEVTOOLS=true
  • H2 Database: For H2 database issues, ensure the H2 port is available and not blocked by firewall
  • Materialization Issues: For file path errors or materialization problems, see the Local Materialization troubleshooting guide

# Connection problems

# Retrieving the host (Docker-based installations)

You can usually connect to your Docker host from inside a container by using this IP address: 172.17.0.1. This is the IP address of the gateway between the Docker host and the bridge network you are using default networking.

If it is not working, you can retrieve your Docker host's IP address running the command

nslookup host.docker.internal

or looking at the assigned IP for host.docker.internal from the hosts file:

  • in Windows at C:\Windows\System32\drivers\etc\hosts
  • in Linux at /etc/hosts.

Other alternative to retrieve the ethernet ip network of your machine. Use the command:

  • in Windows
ipconfig
  • in Linux
ifconfig

# Networking problems

# Missing Docker networks (Docker-based installations)

System support version of docker compose 1.29.0+, we recommend using version 2.24.7+ (opens new window) (Docker Desktop v4.29.0+ (opens new window)) to avoid networking issues such as:

# Issue 1: git-mirror service being unable to access address of git-mirror-db

git-mirror | nc: bad address 'git-mirror-db'

# Issue 2: Nginx configuration references the upstream server named identity-service, but it cannot find the host

 nginx host not found in upstream "identity-service" in /etc/nginx/conf.d/default.conf:74

# Issue 3: the store-server-db hostname cannot be resolved using getaddrinfo

getaddrinfo ENOTFOUND store-server-db

# Port conflicts

# Windows Desktop

  • Verify that ports 8080, 8090, 4300, 3000, 3001, 8666, and 9092 are not in use by other applications
  • Ports can be customized using environment variables in a .env file at %AppData%/OntopicSuite:
    • LOCAL_PORT (default: 8080) - Main application port
    • ONTOPIC_SERVER_WEB_API_PORT (default: 8090) - Ontopic server web API port
    • ONTOPIC_SERVER_POSTGRES_PORT (default: 4300) - PostgreSQL wire protocol port
    • STORE_SERVICE_PORT (default: 3000) - Store service port
    • WEBSOCKET_DOC_PORT (default: 3001) - WebSocket document synchronization port
    • PROCESS_SERVICE_PORT (default: 8666) - Process service port
    • H2_PORT (default: 9092) - H2 sample database port
  • See the environment variables documentation for a complete list of configurable ports

# Logging info on Ontopic Suite Desktop

# On Windows

You can obtain the logs by opening the files at %AppData%/OntopicSuite/logs.

# Stopping Docker compose

Be sure to stop Ontopic Suite with the command:

docker compose -f docker-compose.yml -f tutorial/docker-compose-tutorial.yml down

It will stop and remove containers and networks created. It is the best way to ensure that changes applied in the repository are used when rerunning Ontopic Suite.

← Web API →