Skip to content
HomeDock OS

Why Your App May Not Be Available Right After Installation

When launching an application in HomeDock OS, the system attempts to reach it through a path like /app/8080, where 8080 is the assigned port for the app and it may vary per app.

This path initiates a detection process that determines whether the application is already running and whether it communicates over HTTP or HTTPS.

However, it’s possible that the application isn’t ready yet, even if installation appears marked as complete. Here are the most common reasons and how to address them:

1. Incorrect Port Selection

Some applications expose multiple ports. HomeDock OS typically selects the first available port, but that port might not correspond to the graphical user interface. For instance:

ports:
  - "8080:9000"
  - "8081:80"

In this case, HomeDock OS may direct you to /app/8080, when the actual UI of the application is on port 8081. To fix this:

  • Open the Dashboard.
  • Locate the app and check its port mapping.
  • Double-click the red port mapping (8080:8081, for example) and adjust it to the correct port if needed.

2. App Is Still Starting Up

Applications like WordPress, Nextcloud, or others with embedded databases or large dependency chains may take longer to start after installation. Even if the loader completes, the app may still be initializing.

What to do:

  • Wait 15–60 seconds and refresh the page.
  • Monitor system resources to ensure the app is not stuck during boot.
  • Check the logs of the application on Control Hub so you can ensure the full initialization process is complete.

3. Remote Access Blocked by Router

When accessing your HomeDock OS instance from outside your home network (e.g., using a mobile network), the port may not be open on your router.

  • This issue does not affect cloud instances.
  • From within your LAN, apps should open normally, even when accessing homedock.local.

Solution:

  • Either forward the necessary ports in your router settings,
  • Or use the WireGuard VPN from HomeDock OS on the App Store to connect as if you were inside your network when you’re out.

4. App Runs in Host Mode (Advanced)

Some applications run using Docker’s network_mode: host, which bypasses normal port exposure. This makes it impossible for HomeDock OS to detect which ports are actually in use and they will be mapped as hostmode.

Implications:

  • /app/PORT will fail if the app doesn’t explicitly expose that port.
  • These apps must be manually configured in the Dashboard knowing specifically in which port operates the app, for example, Plex is markes as hostmode and operates in the port 32400.

We’re working on an automatic detection method for hostmode apps, but currently, manual adjustment is required. We initially experimented with a per-app port scanner, but it proved to be too resource-intensive and was ultimately discarded by the team.

Instead, we are now planning a default port mapping system for each application, which will soon allow HomeDock OS to intelligently detect the most likely interface port even in hostmode scenarios. This feature will improve compatibility with complex apps and reduce manual configuration requirements.

Summary

If your newly installed app doesn’t open immediately:

  • Double-check the port mappings.
  • Give it a bit of time to boot.
  • Ensure ports are open if accessing remotely.
  • Handle hostmode apps manually.

These issues are normal given the diversity and complexity of the Docker ecosystem. Most of the time, they can be resolved in seconds with a quick port adjustment or a refresh.

Getting Support

Still need help? We’re more than happy to help! Email us at support@homedock.cloud or join the conversation and submit a ticket on our Discord server.