Get started

First Startup

Initial connection, account security, and initial configuration.

1. Check Container Status

docker compose ps
docker compose logs nasdash

Wait for the healthy status, then open http://192.0.2.10:2504 on your private network, replacing the example address. New installations start with securityMode: private and setupPending: true, no sample devices, services or Docker host, and one Home page with a clock and a weather widget. Existing installations keep their settings and do not enter the new guide.

2. Enter the setup code

Sign-in screen asking for the setup code
NasDash 0.3.6 · new installation · English interface · captured 29 October 2026.

The first-start sign-in screen asks for the setup code printed once in the container logs as Setup code: XXXX-XXXX-XXXX. It is the first password for admin; no viewer account is created by default. If you set NASDASH_ADMIN_PASSWORD, enter that password instead. After signing in, NasDash opens /setup.

3. Follow the five-step guide

Language and look step of the first-run guide
NasDash 0.3.6 · new installation · English interface · captured 29 October 2026.

The administrator guide has five steps:

  1. Account: choose and confirm a new password for admin, at least 12 characters long.
  2. Language and look: choose the language, light or dark mode, and a bundled wallpaper.
  3. Integrations: connect your machines and services; Docker is optional.
  4. Widgets for Home: start with the widgets already on Home and suggestions based on your integrations. Untick a listed widget to remove it when you continue.
  5. Access: keep the instance private or open it for anonymous reading.

From step 2 onward, Skip the guide ends the guide and keeps saved choices; remaining settings can be changed later. Finishing or skipping clears the setup-pending state through /api/setup. Choosing public mode creates viewer if missing, with access to all pages and widgets initially. Anonymous visitors use that account’s permissions. Restrict them in Settings → Users and access. Its random password is never printed; set one there only if someone should sign in as viewer.

Dashboard tour

Dashboard tour bubble pointing at the pages
NasDash 0.3.6 · new installation · English interface · captured 29 October 2026.

After you finish or skip the guide, a short dashboard tour starts. The page dims while a button or widget stays lit, with bubbles explaining pages, widgets, edit mode, Add a widget in the edit bar, Settings, and hiding sensitive information. On phones, the buttons inside the menu are grouped into one menu step. Skip closes the tour before the final bubble; the final bubble has Got it. Replay it from Settings → Help → Replay the tour.

4. Configure Docker (optional)

Choose the connection you need in Settings → Integrations. The following address applies only after enabling the optional local proxy.

Docker management is optional. Choose Portainer, Dockhand, an HTTP(S) Docker-compatible API, or a Unix socket. The local socket proxy is one option; Portainer and Dockhand do not require it. See Docker connections.

The default command starts NasDash alone. For the optional local proxy, run the command below, then choose Address in Settings → Integrations → Docker. Enter docker-proxy in the host field and 2375 in the port field; the resulting endpoint is http://docker-proxy:2375. Keep the profile enabled on recreates and preserve the existing data mount.

docker compose --profile docker-proxy up -d
Name                   Local Docker
Docker address / host  docker-proxy
Docker API port        2375

If NasDash and the proxy do not share the same Compose network, this name will not work. Use the corresponding scenario in Remote Docker Hosts.

5. Build your Home page

Home starts with a clock and a weather widget even if you skip widget selection. Enable edit mode, then click Add a widget in the edit bar to open the library and add more. Configure each widget’s sources as needed.

On an empty page, administrators see a dashed Add a widget slot. Clicking it enters edit mode and opens the widget library. Other users see a single line of text indicating that there is nothing to show yet.

The initial appearance uses /wallpapers/nasdash-aurora.jpg, card opacity 60 %, surface blur 24 px, wallpaper veil 15 % and the Lucide icon set. Adjust it in Settings → Appearance; see customization. There is no sample infrastructure to remove.

6. Create a Reference Backup

Back up the functional state before adding Tailscale, Proxmox, or Glances secrets. This provides you with a clean rollback point.

Missing setup code or lost access

The setup code appears once, after the administrator password hash is saved and before the server is ready. Inspect the complete startup logs, including warnings/stderr. Restarting or rebuilding does not print a new code. If NASDASH_ADMIN_PASSWORD was set when the account was created, use that first password instead.

docker compose logs nasdash

Changing NASDASH_ADMIN_PASSWORD never resets an existing account. Never delete the data folder to regain access. Back up the complete data store, then stop NasDash and use offline recovery with the same data mount and runtime UID/GID. Forgot it? on the regular sign-in screen shows the same recovery command:

docker compose stop nasdash && docker compose run --rm --no-deps --entrypoint node nasdash scripts/reset-password.mjs admin && docker compose up -d nasdash

Enter and confirm a new password of at least 12 characters; input is hidden. The helper preserves other accounts, permissions, keys and integrations, and revokes old sessions for the selected account. Run it with the same mount and runtime UID/GID. Use an SSH terminal on Synology if the UI cannot attach a terminal. Correct errors before starting again. The helper is available in version 0.2.2 or later; the immutable 0.2.1 image has no recovery helper.

Share installation feedback

Use the GitHub issue chooser: User feedback for experiences, Bug report for problems and Feature request for suggestions. Include application/platform versions and sanitized settings. Remove setup codes, password log lines, keys, tokens and private infrastructure data.

The recovery helper rejects password command-line arguments. For automation, feed one line through standard input using your secret-management tooling; do not put passwords in shell history or logs.