NiaDocs
Latest
Menu

Nia documentation · Latest

First-run setup

Find the one-time setup token, create the administrator credentials and safely resume an interrupted installation.

A new Nia instance protects its setup wizard with an installation-specific one-time token. The token is generated when an empty instance starts. It is written to the service log and to a file in the persistent data directory; it is never returned by the API.

Find the setup token

Docker or Docker Compose

Read the startup log:

docker logs nia-todo

With Compose:

docker compose logs nia-todo

The persistent token file is /data/setup-token inside the container. If the startup log is no longer available, read it without copying it into shell history or another file:

docker exec nia-todo cat /data/setup-token

Debian or Ubuntu

Read the service log:

sudo journalctl -u nia-todo

The persistent token file is /var/lib/nia-todo/setup-token:

sudo cat /var/lib/nia-todo/setup-token

The file is created with restrictive permissions. Treat the token like a temporary administrator credential until setup has completed.

Complete setup in the required order

  1. Open http://YOUR-SERVER:8753/setup.
  2. Enter the one-time setup token.
  3. Set the separate administrator password.
  4. Create the first user account. This account is created with administrator rights.
  5. Sign in at / and continue instance configuration in /admin.

The same account signs into all enabled modules. The first-run wizard does not create separate Shopping or Recipes credentials. Users choose visible modules in their own settings; sharing a project, shopping list or cookbook is a separate action inside the app.

The backend enforces this order. Creating the first user before setting the administrator password fails, even when the setup token is valid.

Resume an interrupted setup

The same token remains valid for the entire two-step setup and survives service or container restarts. If setup stops after the administrator password was saved:

  1. Start the service again if necessary.
  2. Open /setup again.
  3. Enter the same token.
  4. Continue with creation of the first user.

GET /api/setup/status exposes only setup-state booleans so the wizard can resume at the correct step. It never returns the token.

Token consumption

The token is not consumed after the administrator-password step. It is deleted only after the first user has been committed successfully and setup is marked complete.

After completion:

  • the token file no longer exists;
  • the token cannot be reused;
  • restarting the server does not create another setup token;
  • the first-run endpoints cannot create another administrator or first user.

Do not place a real token in screenshots, issue reports, command examples, or copied service logs.