Setup wizard

The first time anyone opens Restow, it runs a one-time setup wizard: “Initial setup”. The steps are Language, Setup token, Operator notice, Operating mode, Organisation and admin, Mail transport and Review. The wizard cannot be re-run once it completes: it creates the first administrator, the installation’s settings, the acceptance of the operator notice and an audit entry in a single transaction, and locks itself the moment that transaction commits. If it’s interrupted partway through, nothing of the setup is left behind, and you start over. A lost admin account is recovered from the server’s command line afterward, never through the wizard (see Recovering administrator access).

Step 1: Language

The wizard starts with two cards, English and Deutsch, each named in its own language. The one that matches your browser’s language is preselected, and the whole wizard switches to a language the moment you pick it, so you read the rest of the setup in it. It is also the language of the mails and reports of your own organisation, the tenant the setup creates. The language switcher in the header works at any step, as on every sign-in page; the language that is active when you finish is the one that is saved.

Step 2: Setup token

The second step, “Confirm that you run this server”, asks for the setup token. It is a one-time code that proves you operate this server: only someone who can read the server’s log can see it, so knowing the address of a fresh installation is not enough to take it over. It stops working once the setup is finished. The server checks the token again when the setup is saved, whatever the browser does.

Where to find it. The install script prints it at the end of the installation (from 0.2.0). Until the setup is complete, the api container also writes a one-time token to its log at every start. Show it on the server with:

cd /opt/restow && sudo docker compose logs api | grep 'SETUP TOKEN'

/opt/restow is the directory of the install script; use the directory with your Compose file if you chose another or installed by hand.

The token looks like K7PQX-3MZRA-T9WHE-2BNCV (four groups of five characters); upper or lower case and dashes do not matter. Each restart of the api issues a new token, so use the one printed last. If the api restarts while you are in the wizard, the wizard notices and asks for the new token; your entries are kept.

Unattended installs. To fix the token in advance, set RESTOW_SETUP_TOKEN in .env (at least 16 characters, spaces and dashes not counted; for example openssl rand -hex 16). The wizard then asks for that value, and the token is never written to the log. The api refuses to start with a shorter value. The variable has no effect once the setup is complete. A script that runs the setup sends the token in the X-Restow-Setup-Token header, and the acceptance of the operator notice in the body of POST /api/v1/setup as "disclaimer": {"version": "...", "accepted": true}, with the version that GET /api/v1/setup/state reports.

A wrong or outdated token is refused (urn:restow:problem:setup-token-invalid); copy the token again from the log.

Step 3: Operator notice

The wizard continues with a notice titled “Your responsibility as operator”. You must accept it before you can continue, and the server refuses to save the setup without it. It says that Restow is a tool for backup and archiving that writes your data to storage you operate, and that what happens on the hardware and storage layer is your responsibility as operator. Its points are: Restow is no replacement for a backup strategy (keep an independent copy, follow the 3-2-1 rule), hardware and storage, ransomware and deletion (data is only immutable if the storage makes it so, with WORM or Object Lock; since 0.4.0 Restow can set Object Lock on an S3 repository for you, and delays deletion on directories, which the storage does not enforce: see Immutable backups and the Operator notice), encryption keys, network and access security, regular restore tests, the archive and GoBD (the archive features are designed for GoBD-compliant use; whether your whole procedure is compliant is your responsibility, and Restow gives no legal or tax advice), and no warranty beyond the license terms. The full text is in the wizard; Operator notice explains what it covers.

Tick the box to continue. The acceptance is saved together with the setup: Restow stores which version of the text was accepted, when, and from which client address, records the new first administrator as the person who accepted it, and writes the acceptance to the audit log.

Step 4: Operating mode

Choose how Restow will be reached:

Local mode: reachable via IP address or localhost, no public domain. Admins sign in with the emergency password and an authenticator app code.
Public mode: reachable via your own domain over HTTPS. This is what unlocks passkeys and self-service restore.

In public mode you also set the public URL: exactly the address browsers open (for example https://restow.example.com), no path. It defines the passkey domain and the Entra redirect URI everywhere else in Restow. You can change the mode later in Settings.

Time zone (since 0.4.2)

The same step asks for the time zone of the installation. The time zone of your browser is preselected; pick another from the searchable list if the server belongs to a different one. Updates that an owner plans for a date and a time are read in this zone, the Updates tab shows their times in it, and your own organisation, and every tenant created later, starts with it for its schedules (a tenant can change its own in its customer data). The review at the end shows it.

You can change it later under Installation → Server & operation → Server. If you leave it out (a script that sets the installation up through POST /api/v1/setup may omit timeZone), RESTOW_TIME_ZONE applies, then the process zone TZ, then Europe/Berlin. An installation that was set up before 0.4.2 has no zone of its own and uses that same order until an owner chooses one. See The installation’s time zone and Environment variables.

Passkey readiness

Restow only offers passkeys once it can verify the domain is cleanly connected: the public URL must be set, served over HTTPS, and the browser’s reported origin must match it exactly. The wizard checks this live and shows one of:

Reason shown	What it means
Local mode does not bind a domain, which WebAuthn requires.	You’re in local mode.
No valid public URL is set.	The public URL field is empty or invalid.
The public URL is not served over HTTPS.	Certificate or proxy isn’t in place yet.
The browser reports a different origin than the configured URL.	DNS or a proxy points somewhere other than what you typed.

Until passkey readiness is reached, sign-in falls back to the emergency password path with a mandatory authenticator app (TOTP): this is the designed fallback, not a degraded mode.

Step 5: Organisation and first admin account

First the name of your organisation, the one that runs this installation, for example your company (from 0.2.0). Restow sets it up as your own organisation, the place for your own backups, and shows it as such. The account below is the provider admin: it sets up Restow and creates tenants. Give it a name, an email and an emergency password (at least 12 characters). Right after signing in for the first time, you set up an authenticator app; from then on Restow asks for its code together with the password on every sign-in. Once passkey readiness is reached, add a passkey under Sign-in security in the user menu; it’s optional at setup time.

Step 6: Mail transport

How Restow sends notifications: reports, alerts, invitations. (The archive’s journal intake is separate and receive-only; it has nothing to do with this setting.) Pick a transport:

SMTP server: host, port, connection security (STARTTLS on 587, implicit TLS on 465, or unencrypted for an internal relay only), optional username/password, sender address.
Microsoft Graph (Mail.Send): sends as the Restow Entra app registration, as an application. Requires the Mail.Send application permission with admin consent (see First steps and docs/MICROSOFT.md in the product repository); an Exchange Online Application Access Policy can restrict it to one sender mailbox. A Mail.Send permission that you grant later takes effect once Restow’s cached token expires: this mail does not fetch a new token after a refusal, as backups do since 0.4.7. The Entra tenant is a tenant ID (a GUID) or a verified domain such as contoso.onmicrosoft.com; since 0.4.5 the wizard refuses anything else with 422, as Settings already did (“Enter a tenant ID (GUID) or a verified domain such as contoso.onmicrosoft.com.”).

Send a test message to the admin account before continuing. It shows right away whether the transport works, and a failed test does not block finishing the setup (fix the transport afterward in Settings if needed).

Skip for now (from 0.2.0). The step is optional: choose Skip for now to finish without a mail transport. Without one, Restow sends no alert or report e-mails, and invitations and set-password links are not sent by mail: you copy the link and pass it on yourself. Set it up later under Installation → Installation → Notification mail (Notification mail); until you do, the setup list on the dashboard keeps “Notification mail tested” open. The review then shows the mail transport as “Not set up”. If you come back to this step and choose Next, the form is validated and used.

Step 7: Review

Check every entry (language, operating mode, public URL, time zone, organisation, admin account, mail transport or “Not set up”, test result), then finish. Restow signs you in automatically; if that step fails, the setup itself is still saved and you sign in manually.

Next: First steps to connect a source and take your first backup.

Recovering administrator access

If an owner of the provider team, for example the last one, has lost their passkey, authenticator app or password, recover the access on the server, in the api container:

docker compose exec api restow admin list
docker compose exec api restow admin recover --email owner@example.com

admin list shows the administrators of the installation with their role, their sign-in methods (password, authenticator app, number of passkeys) and whether the account is active. admin recover asks for confirmation and for a new password (at a hidden prompt, at least 12 characters), then removes the owner’s authenticator app and passkeys and ends all their sessions. The owner signs in with the new password and sets up an authenticator app again before anything else, like the first administrator after setup. The recovery is recorded in the audit log as “Administrator access recovered on the server’s command line”.

It works for owners only. Every other administrator is reset by an owner in the web interface.
For scripts, pass the new password on standard input with --password-stdin --yes (the first line is read; --yes skips the confirmation), for example docker compose exec -T api restow admin recover --email owner@example.com --password-stdin --yes < new-password.txt. Delete the file afterwards.
The command uses the api container’s own configuration and talks to the database directly: it needs no running api and opens no port. Nothing secret is printed. docker compose exec api restow help lists the options.

Whoever can run a command in the api container already controls the server, its database and its keys, which is why recovery lives there and not in the web interface.