First boot
The first time you log in to the desktop, the installer opens again. It is the same program, Calamares, this time setting up your account rather than the disk. That is onboarding. It is the only part of Based that wants a network. Everything else, including the apps the session opens on its own, works on a plane. The pure editions, pure Omarchy and SwayOS, have no onboarding.
It starts from the login, runs as you, and never opens in the live session.
The pages
- Welcome.
- Organization, on Based Workstation and Based Poweruser: is this a work computer? Enter your work email or your organization's domain to join it, or skip it on your own computer. Accounts has what joining does.
- Git: the name and email your commits carry. It leaves an identity git already has alone.
- Online Accounts, on the editions with cloud steps, while one is still to do. See below.
- The steps themselves, one after another on the progress page.
- Summary: one row per step, marked Done, Next login, Skipped or Failed. Under a step that did not finish, one line says why and what happens next.
- Finish.
The few steps that change the system itself, such as enrolling a Secure Boot key, ask for your password in the system's own password dialog, which names the step. Cancel it and that step waits for your next login; Finish setting up Based offers it again.
You can cancel on any page before the steps start. Nothing breaks, and the window does not come back by itself: the steps that need no answer from you run quietly at your next logins, and the rest wait for Finish setting up Based.
Online Accounts
The page is a copy of Online Accounts in GNOME Settings: Your Accounts lists what is already connected, and Connect an Account lists the providers you can add, the Work or School Account first. Every provider opens the desktop's own Settings to add it. Accounts has what each row sets up.
Where the edition lacks the sign-in tool these rows drive, onboarding goes from Welcome straight to the steps. The Retro editions have no GNOME Settings, so they have no Work or School Account row. On Retro WhiteSur the rows are KDE's own and open System Settings. On Retro Chicago95 the page has no rows, and Nextcloud's own desktop client is where you sign in to a Nextcloud.
Nothing is set up until you add an account. Add none and go on, and setup asks again at your next login. Finish setting up Based shows the page again.
What it sets up
Which steps you see depends on the edition. Every edition with onboarding has these two:
| step | what it does |
|---|---|
| SSH key | generates your key, unless you already have one |
| GitLab SSH key | uploads the public half to your GitLab, and is skipped where none is set up |
The editions with the Online Accounts page add the cloud steps behind it:
| step | what it does |
|---|---|
| Cloud accounts and services | records what you approved on the Online Accounts page |
| Cloud account | checks the accounts you approved, and signs you in again when a session has expired |
| Nextcloud app password | makes a password for the file sync client |
| Mail credentials | makes one for the mail client |
Editions add their own. Based Workstation, Based Poweruser, Based GNOME and the Zorin look add Flatpak apps and Thunderbird's mail, calendar and contacts. Based Workstation and Based Poweruser add a run of development steps: editors, the shell, terminal tools, the language runtimes, Kubernetes and database clients. Docker is already in their image.
What it leaves for later
A step that needs the network is not started offline. Onboarding waits up to 60 seconds for a connection first, and if there still is none, those steps show Next login on the Summary. No half-done state is recorded.
Every later graphical login runs the steps still pending quietly, with no window, so connecting to wifi and logging in again is usually all it takes.
A step that needs an answer from you does not run in that quiet pass. If onboarding ran one and it did not finish, the window opens again at your next login on that step alone, with no Welcome page. When the step needs the network, that login waits 20 seconds for one and shows nothing if none comes. The Summary of that run has a Don't ask at login box: tick it and the step stops coming back at login. It stays pending for Finish setting up Based, the entry in your apps that runs onboarding again:
based-onboard-calamares --force
It shows Welcome, every step still pending, and the Online Accounts page again where there is one.
Two other commands are worth knowing:
based-onboard-tasks list # what is done, what is pending
based-onboard-tasks run # run the pending ones now
Those two have no menu entry. They are commands only.
Flatpak apps, offline
The desktop comes up complete with no network, because the flatpaks the first session opens are already in the image: Zen, and the adw-gtk3 theme pair that dresses GTK 3 apps, on the editions that use them. Every other flatpak comes from the Flatpak apps step once you are online: the messengers on Based GNOME and the Zorin look, and a longer list of apps on Based Workstation and Based Poweruser. It buys a much smaller image, and it is why an app you expected may not be there on a machine that has never had a connection.