NixOS with AwesomeWM on a Framework laptop

Framework is a company that makes laptops that are easily repairable. AwesomeWM is a modular tiling window manager. NixOS is a Linux distribution that is configured using a declarative, idempotent language. This is a blog post about how to install and configure NixOS using AwesomeWM with no display manager (i.e. using startx) on a Framework laptop. I was inspired to write this after receiving help from elly’s post about installing Alpine on a Framework laptop.

Install NixOS

Create install medium

Download a copy of the NixOS installation media. I used the Gnome graphical installer, but any of them will be fine. Once complete, you can burn the installation image to a USB flash drive using something like

sudo dd if=/path/to/downloaded/image.iso of=/dev/sdX bs=4M status=progress

Disable secure boot

Next disable secure boot (at least temporarily) in order to boot the installer.

reboot the computer
repeatedly press F2 until you see the UEFI BIOS menu
go to the Security tab
go the Secure Boot
change “Enforce Secure Boot” to disabled
press F10 to save and exit

Run installer

Reboot the computer and repeatedly press F10 until the boot menu appears. Select the entry that has “USB” in it. Follow the prompts to install NixOS. You might need to connect to a WiFi network, close the installer, and reopen the installer. At the end of the installer, when prompted for which desktop environment to install, select “None / terminal only”. Don’t worry, we’ll be installing AwesomeWM shortly.

Connect to WiFi

After restarting and signing in at the login TTY, reconnect to the WiFi by running nmtui and following the prompts.

Configure NixOS

There are many ways to set up a NixOS configuration. I personally use a repository with Nix flakes. By default you’ll find your configuration in /etc/nixos/. In this section, I’m going to provide statements that you’ll likely want to include in one of your NixOS configuration files. Which file to put it in is a matter of preference, and is left up to the user, though I’ll provide links to where I included them in my repo.

Kernel version

Wifi, Bluetooth, and graphics will require Linux Kernel 5.16 or greater. I simply set mine to install the latest for now.

source

{
  boot.kernelPackages = pkgs.linuxPackages_latest;
}

Backlight

xbacklight doesn’t work out of the box. Get it working with

source

{
  hardware.acpilight.enable = lib.mkDefault true;
  hardware.sensor.iio.enable = lib.mkDefault true;
  services.udev.extraRules = ''
    ACTION=="add", SUBSYSTEM=="backlight", KERNEL=="intel_backlight", MODE="0666", RUN+="${pkgs.coreutils}/bin/chmod a+w /sys/class/backlight/%k/brightness"
  '';
}

Bluetooth

Enable bluetooth with

source

{
  hardware.bluetooth.enable = true;
}

Manage bluetooth through the CLI with bluetoothctl.

Fingerprint Scanner

Enable the fingerprint reader with

source

{
  services.fprintd.enable = true;
}

Enroll your fingerprint with sudo fprintd-enroll $USER. You’ll then be able to user your finger print when signing in on a TTY and when using sudo.

Increase the TTY console font

Because Framework laptops have high pixel density monitors, the main TTY console can be hard to read. Installing and enabling a larger font can help.

source

{
  environment.systemPackages = with pkgs; [
    terminus_font
  ];
  console = {
    earlySetup = true;
    font = "${pkgs.terminus_font}/share/consolefonts/ter-132n.psf.gz";
    packages = with pkgs; [ terminus_font ];
  };
}

Specify working touchpad drivers

Curiously if you install Gnome or KDE, NixOS will figure out the the correct (or at least a working) touchpad driver. When using AwesomeWM with no display manager, we’re on our own. Specify using the synaptics driver with some reasonable configuration.

source

{
  services.xserver.synaptics = {
    enable = true;
    twoFingerScroll = true;
    accelFactor = "0.075";
    fingersMap = [ 1 3 2 ];
  };
}

Configure AwesomeWM

Some settings here are to help make the menu bar and title bars readable on the high DPI monitor.

source

{
  services.xserver.displayManager.startx.enable = true;
  services.xserver.windowManager.awesome = {
    enable = true;
    luaModules = with pkgs.luaPackages; [
      luarocks # is the package manager for Lua modules
      luadbi-mysql # Database abstraction layer
    ];
  };
  services.xserver.dpi = 180;
  environment.variables = {
    GDK_SCALE = "2";
    GDK_DPI_SCALE = "0.5";
    _JAVA_OPTIONS = "-Dsun.java2d.uiScale=2";
  };
}

Notice the this config enables a startx display manager. In fact, this is configuring NixOS to be able to do startx without a display manager. Create an .xinitrc with

echo awesome > ~/.xinitrc

AwesomeWM bells and whistles

With all of the configuration up until now, after running nixos-rebuild switch ..., (and probably restarting), you should be able to get into Awesome by signing in at the login TTY and running startx. If you’d like a more custom desktop with most of the function keys working, try cloning my awesome config:

git clone --recurse-submodules --remote-submodules https://git.kindrobot.ca/kindrobot/awesome.git ~/.config/awesome`

and reload nix by pressing Ctrl+Super+R.