Restart Required

If you open HomeDock OS for the first time and see a Restart required screen saying the setup window is closed instead of the regular setup wizard, nothing is broken, that means you came too late to the onboarding process. The first-time setup window has a time limit, and it has expired.

This screen only ever appears on an instance where no account has been created yet. If you have already completed setup, you will never see it.

Reopening the Setup Window

Restarting HomeDock OS opens a new setup window. Pick the method that matches your installation:

Linux headless

sudo systemctl restart homedock.service

HomeDock OS Desktop

On our Desktop application for Windows and macOS, quit HomeDock OS Desktop and reopen it. Closing the window is not enough. HomeDock OS Desktop keeps running in the background and so does the service, which means the setup window stays expired. Quit it properly:

• Windows: right-click the HomeDock OS icon in the system tray, near the clock, and select Quit HomeDock OS Desktop.
• macOS: right-click the HomeDock OS icon in the menu bar and select Quit HomeDock OS Desktop.

It will take a few moments for the application to fully quit. Then launch HomeDock OS Desktop again.

Docker

sudo docker restart homedock

Cloud instances

Restart the instance from the Administration Panel over your Cloud Instance:

Settings > Management > Reboot

Once it is back up, open HomeDock OS again and the setup wizard will be waiting for you.

Why This Limit Exists

Before you create your account, the setup page has to be reachable by anyone who can open HomeDock OS in a browser. That is unavoidable, it is the page where your account gets created, so there is no password to ask for yet.

The risk is that on an instance completely left un-configured, that page stays reachable forever. Someone else on your network, or on the internet if the port is exposed, could reach it before you do and create your administrator account with credentials of their choosing, locking you out of your own installation.

Limiting the window closes that gap. Setup is accepted only during the first 15 minutes after HomeDock OS starts. Once that time passes, the only way to reopen it is to restart the service, and restarting requires control of the machine HomeDock OS runs on, which is precisely the proof that you are its owner.

This is the same approach Portainer takes with its own initial-setup window.

Why Not a Setup Token

A common alternative is to print a one-time token to the container logs or write it to a file, and require it to complete setup.

We considered it and chose not to. A token assumes you have console or log access the moment HomeDock OS first starts, and that is not true everywhere HomeDock OS runs. Neither HomeDock OS Desktop on Windows and macOS nor our cloud instances give you a console to read a token from. A token would mean a different setup flow on every deployment target, and a broken one on some.

A time-limited window behaves identically everywhere, and it guarantees the important part: the setup page cannot stay open indefinitely.

Credits

This behavior was introduced in HomeDock OS 2.1.6.164, following a security report from EQSTLab, the GitHub account of EQST — Experts, Qualified Security Team — the offensive security research group at SK Shieldus, in South Korea.

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.