How to install mauveine

Last updated: 6 June 2024

In this document

Option 1 - Create a mauveine SD card image

Thanks to Cloudsmith for providing hosting for the mauveine images and packages.

This is the recommended way to install unless you are installing on an existing system, in which case see below. but do bear in mind that installation has only been tested on Pi OS 2022.9 and later.

The most recent release can be found on GitLab.

The pre-built images

In general using the most recent package appropriate to your system is recommended (i.e. arm64 or arm32). Sometimes older hardware will not work with the most recent OS, and in these circumstances the bullseye packages may be of use.

Four different SD card images are available

name description Use case
arm64 64 bit OS based on Raspberry PI OS Bookworm Recommended for Pi 3, 4, 5, Pi Zero 2, compute modules and newer devices
arm32 32 bit OS based on Raspberry PI OS Bookworm Recommended for older devices
arm64-bullseye 64 bit OS based on Raspberry PI OS Bullseye Try this if the bookworm version does not work with your hardware. Not compatible with Pi 5
arm32-bullseye 32 bit OS based on Raspberry PI OS Bullseye as above, but for 32 bit Raspberry PI devices.

If installing mauveine on an existing system, you are strongly recommended to make a backup of your SD card before installing. There is a small risk of your system being made inaccessible over the network by the process if you are installing on a bullseye based system (but this should be fixable from within mauveine and see below for how to fix this offline).

Installation instructions for prebuilt images

  1. Download the image file that you want to install. Use the “arm64” image for Pi3 and above, CM3 and above and Pi Zero 2 (or equivalent models), use the arm32 image for Pi 1, Pi 2 and Pi Zero (or equivalent models.

  2. On a working system, download the Raspberry Pi imager, available from https://www.raspberrypi.com/software/.

    Use “Choose device” to pick your Pi model if you wish. This should prevent you picking the wrong version of the OS by mistake, but is optional.

    Do not install the default image. From the “Operating System” menu select “Use custom” then chose the image that you downloaded in the file selector.

  3. Install to a SD card with at least 8GB of space.

  4. The mauveine installer will let you set up networking, but you may find it easier to do this from the Pi imager program. It is recommended that you configure account details using the Imager, as otherwise mauveine will create a random user account and password. For systems without a local console, your best option is to open the SD card on another Linux system and get the login details from /home/mauveine/.random-user. SSH login is disabled by default, but if you enable it using the Imager config menu, it will remain active until the setup process has been successfully completed, so using the Imager to create a starting config remains the best option for setup on systems where the screen will not work without being configured first.

    From the config (gear) menu, you can select the following options

    • set hostname to whatever you want
    • Set username and password - this can be anything you want (that’s not already used by Pi OS) except “mauveine” as this account is used internally and is not intended to have login permissions
    • Configure wireless LAN - if your Pi is wireless only, this is especially important. Mauveine can run without a network, but it uses the network to set the time correctly.
    • It’s a good idea to set the locale to the primary location where the clock will be used. Mauveine will use the locale to determine local clock settings by default (but this can be changed from within mauveine).

  5. If you already know the lines to add to set up your screen to /boot/firmware/config.txt (/boot/config.txt on older systems or cmdline.txt, it is recommended that you use an editor to add them before rebooting. For some screens the Pi will boot to a blank screen unless you do this. The screen may be blank while installation is happening and the Pi will reboot multiple times. Eventually you will see the mauveine logo appear, and mauveine should start its setup routine.

  6. Please see the hardware.md document for details as to what to put in these files. They are editable on a Windows machine when an imaged SD card is inserted. On a Linux machine they are contained on the first partition on the SD card, labelled boot.

  7. By default the i2c and i2s interfaces are enabled as these are used for the Real Time clock and sound card interfaces. Screens connected via the GPIO pins may need these disabling again.

  8. The standard image switches to tty8 for a quiet boot and puts console output on tty9 for debugging purposes. When mauveine is not running, it should switch automatically back to tty1, or you can switch to a login prompt by plugging in a keyboard and using Ctrl+Alt+F1 - Ctrl+Alt+F6. Ctrl+Alt+F9 will show you console messages including any errors encountered by mauveine. I would love to allow Ctrl+Alt to switch to and from mauveine while it is running, but the logic to do this seems to be specific to X11, and would be disproportionate to reproduce here.

Option 2 - Install from the repositories

This is the recommended method for installing on an existing system. You can also install directly from git using the installer script (see below), but the repo method is probably better at uninstalling cleanly.

  1. To ensure that you are only getting mauveine packages from the genuine source, Install a copy of the mauveine archive’s keyring on your system by running the following command as root:

    curl -1sLf 'https://dl.cloudsmith.io/public/mauveine/mauveine/gpg.01CD8CF23DCCFDDE.key' |  gpg --dearmor -o /usr/share/keyrings/mauveine-mauveine-archive-keyring.gpg

  2. As root, create a text file /etc/apt/sources.list.d/mauveine-mauveine.list (e.g. using nano) containing

    # Source: mauveine
# Site: https://gitlab.com/mauveine/mauveine/
# Repository: mauveine / mauveine
# Description: An embeddable and configurable alarm clock for Raspberry Pi systems designed for running # on a touchscreen and written in PyQt.


deb [signed-by=/usr/share/keyrings/mauveine-mauveine-archive-keyring.gpg] https://dl.cloudsmith.io/public/mauveine/mauveine/deb/debian any-version main

deb-src [signed-by=/usr/share/keyrings/mauveine-mauveine-archive-keyring.gpg] https://dl.cloudsmith .io/public/mauveine/mauveine/deb/debian any-version main

  3. There are four packages available for installation:

    Name Contents
    mauveine Application only (run from the command line)
    mauveine-service Run mauveine on the framebuffer on startup as a user environment
    fonts-mauveine Required fonts (packaged separately so they can be installed without mauveine)
    plymouth-theme-mauveine Logo to use on system start

  4. To install just the mauveine app (e.g. for running on a desktop system)

     apt update && apt install mauveine fonts-mauveine

    To install mauveine as the primary user interface on your system

     apt update && apt install mauveine fonts-mauveine mauveine-service plymouth-theme-mauveine

Installing mauveine as a service will make alterations to allow mauveine to run smoothly in the foreground on your system. Most or all of these will be reversed if mauveine is uninstalled, but the system is not infallible. See below for full details of how mauveine modifies your system. Installation as an application only for testing purposes should not make any significant changes.

X11/Wayland will not be disabled, and this is up to you to arrange if appropriate.

Installing the mauveine-server package automatically enables automatic upgrades for Raspberry PI OS and mauveine. This can be disabled from within mauveine.

Most users should find the automatic update options provided by mauveine will meet their needs and need not read the rest of this section.

If the standard configurations don’t meet your needs, you can edit /etc/apt/apt.conf.d/55mauveine-unattended-upgrades. If you remove the first line of this file, mauveine will not override your custom configuration.

For reference, and to assist in generating your own configuration, to manually configure mauveine updates the process is as follows:

  1. Install the updater as root using

     apt install apt-unattended-upgrades

  2. Create a file /etc/apt/apt.conf.d/55mauveine-unattended-upgrades with the following contents

     Unattended-Upgrade::Allowed-Origins {
         "Raspbian:${distro_codename}";
         "Raspberry Pi Foundation:${distro_codename}";
         "cloudsmith/mauveine/mauveine:any-version";
 };

 Unattended-Upgrade::Origins-Pattern {
         "origin=Raspbian,codename=${distro_codename},label=Raspbian";
         "origin=Raspberry Pi Foundation,codename=${distro_codename},label=Raspberry Pi Foundation";
         "origin=cloudsmith/mauveine/mauveine,codename=any-version,label=mauveine";
 };

The above automatic update configuration updates both Raspberry Pi OS and mauveine automatically. This may or may not be what you want. To update only mauveine delete the Raspbian and Raspberry Pi Foundation lines from both sections of the file.

Option 3 - Install from the shell on an existing Raspberry Pi

Using a combination of mauveine packages and the installer script is likely to leave your packages in an inconsistent state. It is recommended to uninstall using the method currently in use before switching to an alternative method.

The mauveine repository is available at https://gitlab.com/mauveine/mauveine/. Installing via the Debian packages is the recommended option, but the installer shell script is an available alternative if for some reason the Debian packages aren’t suitable, or for use in a development environment.

  1. Boot the Raspberry Pi from the media that you just created, and log in. It is not recommended to install mauveine unless you have the screen already working and can see the Pi booting on it, as mauveine does not set up the screen itself (unfortunately there are too many different screens to make that process automatic.)

  2. The simplest way to install mauveine on an existing system is to clone the repo and then run the installer. I recommend doing the install from within tmux - the install can take a while on older machines, so this will avoid the install failing in the ssh connection drops. The setup script can be safely re-run but it will still restart from the beginning and it takes a while to work out what things are already installed. The setup program will install everything it needs in order to run.

    If connection is lost, reconnect with tmux -a once you are logged in again.

    sudo apt install -y git git-lfs tmux
tmux
git clone https://gitlab.com/mauveine/mauveine.git
sudo mauveine/tools/mauveine-setup

    See below or use mauveine-setup --help to see what installation options are available. The install is reversible using mauveine-setup -c but this does not remove the mauveine home directory or attempt to uninstall installed packages.

  3. Alternatively, the script can also also be downloaded and run directly from the repo in one command using

    curl \
   https://gitlab.com/mauveine/mauveine.git/raw/branch/main/tools/mauveine-setup \
   | sudo bash /dev/stdin

  4. Installing with no options should be the right choice for most users. When running via curl if you want to use other options, use the command

    curl \
   https://gitlab.com/mauveine/mauveine.git/raw/branch/main/tools/mauveine-setup \
   | sudo bash /dev/stdin -n <options>

    Some useful alternative options are:

    Options Description
    -c Attempt to remove all traces of mauveine from the system
    -f Skip installing additional fonts for a slightly more lightweight install
    -g normally mauveine creates its own system user and runs itself from systemd. This requires granting some extra reasonable security permissions and making changes to the system software (see below). If this is not desired, the -p flag installs mauveine as a user space application only
    -d Install additional tools useful when developing mauveine
    -s Skip installing the on boot splash screen (which does not work on some configurations) which may not be desirable on a general purpose system
    -p Build Debian packages - does not install anything
    -r Reboot the system after install is completed (should not be necessary)
    -q The installer is chatty by default. If you don’t want to watch it do its thing, this can be turned off.
    -y Build a python package (unsupported) - does not provide installation as a service

  5. If for some reason the installer is interrupted. It is not harmful to run it again. The installer can be found in the apps/tools directory once the git repo has been cloned.

Recovery

If you are unable to access your system over the wifi network after install, you may still be able to connect via wired network (the “Info” page in the “About mauveine” menu item will tell you if the Pi has any valid IP addresses).

If your Pi is not booting into the GUI, try attaching a keyboard and pressing Ctrl+Alt+F1 as a console login may be available for debugging purposes. Some useful debugging information may also available via the system console, which is mapped to Ctrl+ALt+F9 by default.

If not, yuu can restore local console access to the following:

  1. Unplug the Pi

  2. Remove the SD card from the Pi and put it in a working computer

  3. Edit the file /boot/firmware/cmdline.txt (or /boot/cmdline.txt on older systems) and add “systemd.mask=mauveine.service” at the end of the line

  4. Reboot

The disabling of console output in the boot process is automatically reversed by mauveine early in the boot process. However, if you experience issues seeing anything at all on the display even when the mauveine service is masked, you may wish to try also removing the parameter fbcon=map:2 from cmdline.txt

You should now be able to log in on the console using a USB keyboard. If the mauveine installer has made your system inaccessible, the most likely culprit is NetworkManager, installation of which is temperamental. Check your network settings in /etc/NetworkManager/system-connections to see if there is anything obviously wrong.

Troubleshooting

You may find some troubleshooting information about why mauveine is not starting by typing

systemctl status mauveine
journalctl -e -u mauveine

You can also try the following to try to work out why mauveine is not starting by starting the system manually as follows:

sudo su - mauveine
/usr/lib/mauveine/env/bin/python /usr/lib/mauveine/mauveine.py 2>&1 > mauveine-debug.txt

(You might need to try /usr/local/lib/mauveine instead if that doesn’t work.)

Running mauveine in this way supplies extra debugging information

The default unix shell account in mauveine images

For security reasons there is no default login account on mauveine images. Raspberry PI OS’s default way of handling this requires the user to change the account name via the text console on first boot and does not work well in the embedded environment mauveine is designed to run in.

Instead of this mauveine creates a random default account name and password, which is visible from the system information in the About box and also in a message before login. By default mauveine ships with this account disabled, and your PIN is required to enable SSH or access the console, but the account details are readable by anyone who can physically put the SD card in another computer.

If you are particularly concerned about the login credentials being accessible on the system, the best way to avoid this is to write a Raspberry PI image with your own username and password configured. Otherwise, the readable details are deleted on the first successful login, so be sure to log in to the UNIX backend once - you will be prompted to change the account name and password and can do so if you want to. After you have logged in once the login credentials will no longer be stored anywhere in plain text.

How mauveine modifies your system

As part of the default install process, mauveine makes a number of changes to the Pi OS which are sensible defaults for running as a headless appliance. They may not be suitable for all users, so they are documented here. They can all be reversed if required, but may be put back if the installer is run again.

Updates OS to latest patches and enables automatic updates

This is good practice for security reasons. No-one wants a pwned alarm clock. A file /etc/apt/apt.conf.d/55mauveine-unattended-upgrades is created, and by default this uses the Debian unattended-upgrades package to keep both the OS and mauveine up to date.

Adds a system user “mauveine” to the Pi

For security reasons, mauveine does not run as root. This means it needs a user to run as. To allow the clock to work properly, this user is added to the following groups: “video,audio,input,i2c,tty”. It is not possible to log on to the system interactively as the mauveine user.

The mauveine user is given permission to control NetworkManager using polkit, and to run some specific systems admin tasks requiring root access via sudo, but otherwise runs with normal user privileges.

The mauveine user’s home directory will not be removed on uninstall, unless you purge all configuration using the debian package (i.e. apt purge mauveine-server)

Changes access permissions for the backlight devices

All users in group “video” are permitted to change hardware backlight levels. This is necessary so mauveine can set the clock brightness and has little to no security impact.

Autologin is disabled

It is not a good idea to use auto-login with mauveine, since it may then be possible to run arbitrary commands as the automatically logged-in user by plugging in a keyboard to the Pi’s USB port, and mauveine allows access to the console to a user with a PIN, or if a PIN is not set. As the automatically logged in user generally has root access, some scallywag with access to your device could cause considerable trouble if you enable autologin (which you can re-enable using raspi-config if you are feeling foolhardy or the risk/benefit calculation works out differently for your use case).

The Debian packages perform this check on install. It is possible that if you re-enable autologin, it will be disabled again when the mauveine service is automatically upgraded. Automatic upgrades can also be disabled if desired.

Installs a splash screen

The mauveine program is intended to be used as an appliance, and this shows the mauveine logo while the system is booting.

Boot parameters

Mauveine adds the following parameters to /boot/cmdline.txt

parameter Purpose
console=tty9 Make errors and warnings available on virtual terminal 9, accessible by pressing Ctrl+Alt+F9 on an attached keyboard when mauveine is not running
splash Shows the splash screen (if installed)
quiet Do not display boot messages
plymouth.ignore-serial-consoles required to make the splash screen work
fbcon=map:2 This prevents a blinking cursor on boot up - the console is re-enabled early in the boot process

Installs mauveine as a systemd service

This allows the clock to start up when the system is turned on.

Converts the system from dhcpcd networking to NetworkManager

The Raspberry Pi team have migrated Raspberry Pi OS to NetworkManager in the bookworm release. Using it now allows the clock to set network settings securely from the GUI.

For systems running the older bullseye release, existing wpa_supplicant configurations are automatically migrated by the mauveine installer so wireless networking will keep working. Systems without NetworkManager can still run mauveine, but it does not support network configuration in those circumstances.

Users in the mauveine group are given full privileges to access and change NetworkManager settings.

Installs its own sound configuration

Linux sound support from the command line leaves much to be desired. In order to provide a “plug and play” sound experience, mauveine will overwrite /etc/asound.conf with a configuration that works for use in mauveine. This may not be generally suitable.

Sadly the new 111111111 audio support in Pi OS Bookworm does not provide a sound interface for programs running outside of a Wayland/X11 session, so mauveine is stuck with trying to support sound through ALSA directly, which is extremely clunky.

If you have created a custom sound configuration, it is recommended you take a backup of it before installing mauveine, and also that you do not attempt to configure the sound device from within mauveine.

Files created by the mauveine installer when installing mauveine as a service

/usr/lib/systemd/system/mauveine.service
Allows systemd to manage mauveine as a service.
/usr/lib/systemd/system/mauveine-quiet-vc-on-boot.service
Support script which re-maps the console to the framebuffer after a quiet initial boot and performs other console setup.
/usr/lib/systemd/system/netmanager-mods-mauveine.service
Automatically converts legacy bullseye WPA Supplicant configuration files to NetworkManager connections on first run.
/etc/asound.conf
Sound devices will be automatically detected and configured by mauveine.
/etc/mauveine/autoupgrades
Used internally by mauveine to record the last selected automatic upgrade mode, so this can be restored if the package is reinstalled.
/etc/apt/apt.conf.d/55mauveine-unattended-upgrades
Configures unattended (background) upgrades for Raspberry Pi OS and mauveine.
This is managed by mauveine by default, and may be overwritten, but this can be disabled by removing the first line of the config file and then editing
/etc/sudoers.d/mauveine-service
Allows users in the mauveine group (typically only mauveine) to run a number of system tasks.
This is required to allow mauveine to configure the system when running as an appliance.
/lib/udev/rules.d/98-backlight-permissions.rules
Allows users in the mauveine group to control the brightness of display backlights
/var/lib/polkit-1/localauthority/50-local.d/mauveine-networkmanager.pkla
Rules permitting user in the mauveine group to control NetworkManager
/home/mauveine/.random-user
This file is only created by the SD card images when no username and password has been supplied when the image was written to the SD card. It is world readable and contains the randomised username and password of the default privileged user account. It is automatically deleted when this user first logs in.

Further hardening

If mauveine finds a file named /etc/mauveine/lockdown on the system it will disable various higher risk options like access to the console. By default, mauveine tries to strike a balance between being secure, and also being usable as a Linux computer, but creating a system with this file will produce a system with more limited access at the expense of being somewhat harder to debug or fix if something goes wrong.