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 open in a new tab when you browse HomeDock OS at homedock.local. OnScreen App windows need a domain of your own — see OnScreen Apps.

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. An OnScreen App Window Stays Blank

When an app opens as an OnScreen App and the window never fills in, several different failures look identical from inside the browser. HomeDock OS tells them apart for you and names the one that applies, so read the message in the window before changing anything.

The address does not resolve. The window reports that the address is not reachable yet and asks for a wildcard DNS record. Each app lives on a subdomain of the name you browse HomeDock OS by, so your DNS has to answer for any name under it. Add *.yourdomain.com pointing at the same address as yourdomain.com and the windows start opening on their own, with nothing to restart. You can check the record before touching HomeDock OS:

dig +short anything.yourdomain.com

If that prints your IP address, the record is in place. If it prints nothing, no certificate will help.

The certificate does not cover the subdomain. The window reports that your certificate does not include *.yourdomain.com. Reissue it covering the wildcard and restart HomeDock OS. If the certificate covers a different domain that you also own, the window offers to send you there instead, because a public certificate authority cannot issue one for the name you are currently on.

Two traps live here. A wildcard covers exactly one label, so *.example.com does not cover app.home.example.com; browsing HomeDock OS at home.example.com means you need *.home.example.com. And a self-signed certificate can never work in a window, because a page loading inside one is not allowed to show you the acceptance prompt. Open the app in a new tab and accept it once, or install the certificate as trusted on the device to remove the prompt for every app.

The address cannot host windows at all. On an IP address, on a name with no dot in it, or on homedock.local, windows are unavailable regardless of your certificate, and apps open in a new tab instead. This is checked before the certificate, which is why the message never mentions certificates in these cases: reissuing one would change nothing.

_{Requirements, the per-app opening modes and the full behavior of app subdomains are covered in OnScreen Apps.}

5. 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.
Read the message in a blank window before changing your certificate or DNS.
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.