Troubleshooting and FAQ

These checks apply to Just Dashboard 0.8.4. Run server commands from the cloned Just-Dashboard directory. For a quick read of the running stack:

docker compose ps
docker compose logs --tail=100

The backend log may contain a generated first-run password. Redact secrets before sharing logs.

I cannot open the sign-in pageCopy Anchor Link

Use the exact URL and port printed by install.sh. It may have chosen a port other than 8443 because the default was occupied.

• Tailscale: confirm both devices are on the same tailnet and use the server's MagicDNS name or address printed by setup.
• SSH tunnel: keep ssh -N -L PORT:localhost:PORT you@server open on your client device, then browse to the installer-printed localhost URL on that same device.
• After an access-setting change: try the printed SSH-tunnel fallback. JD_ALLOWED_CIDRS must include loopback (127.0.0.1/32,::1/128) as well as the network you are using. The Settings page rolls back a restart that fails to come up, but a working configuration that excludes your client still cannot serve you a login page.

If docker compose ps shows a service stopped, read its logs for the startup error. Invalid durations, booleans, CIDRs, or a missing JD_MASTER_KEY cause startup to fail visibly.

The browser warns about the certificateCopy Anchor Link

JD_TLS=internal uses Caddy's own CA. The connection is encrypted, but the browser does not trust that issuer. On a Tailscale install, enable HTTPS for the tailnet in its DNS settings and use the MagicDNS name; then select a Tailscale certificate under Settings → Configuration. An SSH-tunnel installation uses http://localhost over the encrypted tunnel and has no certificate warning. The fallback tunnel for an HTTPS Tailscale install may warn that the certificate belongs to its MagicDNS name rather than localhost.

I cannot finish sign-inCopy Anchor Link

If you manually left JD_BOOTSTRAP_PASSWORD empty, find the one-time password in docker compose logs backend; the login screen then requires a new password. The guided installer prints its chosen or generated password at the end, and that password is not forced to change automatically. A new password must have at least 12 characters and mix three of uppercase, lowercase, numbers, and symbols.

If two-factor enrollment is required, finish it and save the recovery codes shown once. If you already enrolled, use your authenticator or Use a recovery code instead. An administrator can reset another user's two-factor enrollment under Account → Users if both are lost.

If you forgot your password, select Forgot it? on the sign-in page. It shows the command to run from the dashboard's folder on the server, sudo ./scripts/reset-password.sh USER, which prompts for a new password and clears a sign-in lockout. You sign in with that password directly; it is not treated as temporary. An account that is disabled under Account → Users cannot sign in until an administrator turns it back on.

A page is missing from the sidebarCopy Anchor Link

Your sidebar may hide a section. New accounts choose their sections after the first sign-in, and you can change that under Account → Workspace. A hidden section still opens from links and search. If the section is not offered there either, your role does not allow it: What this account can do on Account → Profile lists what your role grants. See Roles and capabilities.

Git or deployment content is missingCopy Anchor Link

The dashboard scans paths from JD_GIT_ROOTS, JD_COMPOSE_ROOTS, and JD_DEPLOY_ROOTS. The bundled backend container must also mount those host directories at the same paths. A local deployment repository outside JD_DEPLOY_ROOTS is refused. Check the configuration reference before widening roots or changing mounts.

For a GitHub push that works on the Git page but fails in a host terminal or SSH after an upgrade, re-run sudo ./install.sh to install gh on the host. If the Git account was connected before 0.7.0, use Use this account for git on the Git page to refresh its credential helper.

No newer version appears, or an update cannot startCopy Anchor Link

Open Settings → Version to see the installed version, the repository and branch it follows, and the check result. When an update is available, the sidebar's notice and the Version page open the same update dialog. JD_UPDATE_CHECK=false disables discovery; it does not remove release notes compiled into the installed build. The in-app update reads JD_UPDATE_REPO and JD_UPDATE_BRANCH and needs to locate the cloned checkout. Keep JD_UPDATE_BRANCH at main, where 0.8.4 is released, and apply any change with docker compose up -d. If the Version page says it cannot find the checkout, set JD_UPDATE_DIR to its real path. You can instead update from that directory with git pull and docker compose up -d --build.

Saved secrets are unreadable after a reinstallCopy Anchor Link

If the dashboard was reinstalled with its data directory but without the original .env, everything sealed with the earlier JD_MASTER_KEY cannot be opened: saved database passwords, deployment variables and credentials, backup credentials, and authenticator seeds. When install.sh finds such data with no .env, it asks for the earlier key; paste it to keep everything readable.

Without the earlier key, databases found in containers and servers that need no password reconnect by themselves: the dashboard repairs their saved connections in place rather than adding a second copy. Other database passwords, deployment variables, and backup credentials have to be entered again. An account with two-factor signs in with one of its recovery codes and enrolls its authenticator again.

What must I keep to restore the dashboard?Copy Anchor Link

Back up JD_DATA_DIR (normally /var/lib/just-dashboard) and keep JD_MASTER_KEY separately. The Backups page lists the dashboard under Coverage and can create a job for its data. If backup jobs encrypt their archives, also export the backup key from Backups → Backup key and keep it with the master key. Without the original master key, stored encrypted credentials and authenticator seeds cannot be read from a restored database. Keep the existing .env when re-running the installer or upgrading.