README.md

March 12, 2025 ยท View on GitHub

Vanilla OS First Setup

This utility is meant to be used in Vanilla OS as a first-setup wizard. Its purpose is to help the user to configure the system to their needs, e.g. by configuring hostname, theme, flatpak apps, etc.

Translation status

Run without building for Testing

Important


You need to install all build and run dependencies first

python3 test.py -d

The "-d" option is the dry-run mode, without it, first-setup will make changes to your system.

Pass the "-c" flag to force the configure system mode.

Test translations:

You can change the used language like this:

LANGUAGE=de python3 test.py -d

Build

Installing build dependencies

sudo apt-get update
sudo apt-get build-dep .

If you want to install the build dependencies manually, have a look in: debian/control

Building

Warning


dpkg-buildpackage places it's output files (Like the .deb file) into the parent folder.

dpkg-buildpackage

or manually with meson:

meson setup build
meson compile -C build

Here you can change the install folder (default is /usr/local), for example:

meson setup --prefix="$(pwd)/install" build

Install

Installing runtime dependencies

These can be found here: debian/control

Tip


If you use apt-get to install the .deb file it will automatically install the dependencies.

Installing

sudo apt-get install ./vanilla-first-setup*.deb

or manually with meson:

meson install -C build

Run

Creating initial user

A special user is needed to run the initial setup for hostname, user-creation, locale, etc.

  1. Create a user
  2. Create the group vanilla-first-setup (Changing the gid is recommended to avoid messing with user groups)
  3. Add the user to group vanilla-first-setup
  4. Create the file /var/lib/AccountsService/users/your_user
[User]
Session=firstsetup
  1. Create the file /etc/gdm3/daemon.conf (replace your_user)
[daemon]
AutomaticLogin=your_user
AutomaticLoginEnable=True

Warning


All users in this group will be deleted on the first reboot after a successful first setup.

Running

vanilla-first-setup

Flags:

  • --dry-run (-d): Don't make any changes to the system.
  • --force-configure-mode (-c): Force the configure system mode, independant of group.
  • --force-regular-mode (-r): Force the regular mode, independant of group.
  • --oem-mode (-o): Use the original equipment manufacturer mode with language, keyboard and timezone selection.

Update translation file

To update the .pot file with newly added translation strings, run:

meson compile -C build vanilla-first-setup-pot

Adjust for Custom Image

Adjusting the scripts

The scripts which are used to modify the system can be found in /usr/share/org.vanillaos.FirstSetup/vanilla_first_setup/scripts/.

Please adjust (overwrite) them to your needs in your image.

Non-GNOME desktops

If you are using a different desktop than GNOME, you will have to adjust /usr/share/xsessions/firstsetup.desktop and /usr/share/wayland-sessions/firstsetup.desktop.

This session is only used to create a new user account. It should be a restricted shell to prevent the user from making changes to the system that will be lost when logging into their own user account.

If your Desktop doesn't offer this feature, just copy the session of your desktop to firstsetup.desktop.