NixOS getting started guide

[_hg_]

I am a complete NixOS newbie, so it took me a while to get things settled. I thought I'd share this here in case it helps someone else. Note, this guide is not perfect and still requires some general Linux knowledge or careful Googling.

Building the system

1. If you are not running the build on a system that has Nix, install Nix (see https://nixos.org/download.html).
   
2. Clone https://github.com/samueldr/wip-pinebook-pro
   
3. Edit both build.sh and default.nix, and replace 19.09 with 20.03. 20.03 is the current stable channel, and it should work better based on conversations in the project's GitHub issues.
   
4. If you are on Manjaro (and maybe other distros?) edit build.sh and change nix-build to $(which nix-build). (Thanks to acsid's fork https://github.com/acsid/wip-pinebook-pr...9f71a0b6cf)
   
5. Run build.nix to build it. Kernel build may take a long time, probably hours.
   
6. Copy the wip-pinebook-pro folder to some storage media (ideally a thumb drive) in case you mess up, so you don't have to build everything again.
   
7. Install:
   

• For SD install: use the dd command below, but make sure you are using the right /dev/mmcblk*. For me this was /dev/mmcblk1.
  
• For install to eMMC with USB adapter: use the dd command below, but change /dev/mmcblk0 to the location of your USB adapter. (Not tested but this should work.)
  
• For install to internal eMMC without adapter: first perform the SD install, then reboot into your new NixOS install on the SD card. Then see steps in the next section below.
  

Code:

lsblk /dev/mmcblk0 && sudo dd if=result/idbloader.img of=/dev/mmcblk0 bs=512 seek=64 oflag=direct,sync && sudo dd if=result/u-boot.itb of=/dev/mmcblk0 bs=512 seek=16384 oflag=direct,sync

Building and installing to internal eMMC from booted SD image

If you saved your built image:

1. Mount the storage media where you saved the wip-pinebook-pro folder.
   
2. Run the dd command above, but change /dev/mmcblk0 to the correct device. For me this was /dev/mmcblk2.
   
3. Shutdown, eject the SD card, and reboot.
   

If you lost your built image like I did and you need to rebuild:
 

1. Set up networking. For wireless, you can do this by creating /etc/wpa_supplicant.conf with the proper setup and then run "sudo systemctl start wpa_supplicant.service". Ethernet may just work with a USB adapter, but I have not tested this.
   
2. Clone https://github.com/samueldr/wip-pinebook-pro. You can pull down the repo using curl or run "nix-shell -p gitMinimal" to temporarily acquire git.
   
3. Edit both build.sh and default.nix, and replace 19.09 with 20.03. 20.03 is the current stable channel, and it should work better based on conversations in the project's GitHub issues.
   
4. Run build.nix to build it. Kernel build may take a long time, probably hours.
   
5. Run the dd command from above, but change /dev/mmcblk0 to the correct device. For me this was /dev/mmcblk2.
   
6. Shutdown, eject the SD card, and reboot.
   

Making a usable system

1. Once you can boot, you will need configuration files before you can use nixos-rebuild. Run "nixos-generate-config" to get a starter /etc/nixos/configuration.nix and /etc/nixos/hardware-configuration.nix.
   
2. Make your configuration. An example is here: https://github.com/tgunnoe/configuration...ration.nix. START SIMPLE. I would leave out anything graphical to start with, you just want to be able to rebuild your kernel and reboot. I may post a followup basic config later. Don't forget to include a reference to the wip-pinebook-pro patches, either using tgunnoe's method (linked) or by cloning the repo locally and referencing it in your imports section as in the repo's README.
   
3. Set up networking. For wireless, you can do this by creating /etc/wpa_supplicant.conf with the proper setup and then run "sudo systemctl start wpa_supplicant.service". Ethernet may just work with a USB adapter, but I have not tested this. Make sure you also set networking options in your configuration.nix so you will have a functional connection after you rebuild!
   
4. Run "nix-channel --update" to update your channel.
   
5. Run "nixos-rebuild boot --update". This should pull down everything and rebuild everything.
   

Once you have a working configuration.nix, you should be able to add packages to it and run "nixos-rebuild switch" without a problem. Note that if you break your configuration, you may have to use the SD card image or the serial console to revert.

[theotherjimmy]

1. Before building, make sure you are on the right channel with "nix-channel --list". I wanted 20.03 but was on unstable, so I had to run "nix-channel --add https://channels.nixos.org/nixos-20.03" followed by "nix-channel --update".
   

I don't think this step is needed, as the channel is specified in the nix expression here https://github.com/samueldr/wip-pinebook...ult.nix#L2.

It's also worth noting that you can use nixos-install to install the system to the SD or eMMC once on the PBP. I had good luck with this method in my setup. This also allows you a chance to create your own partition layout and tweak the /etc/nixos/configuration.nix for the first generation. For example, I use ZFS following the technique in https://grahamc.com/blog/erase-your-darlings on my PBP eMMC, with good results.


These steps look great! Perhaps these should be added to the repo?

[_hg_]

Good point, I'll take out that step. I made a lot of mistakes throughout the process and tried a lot of things to fix the problem, that one may not have been needed.

I actually tried nixos-install from the SD card but couldn't get it to work. I deleted the Manjaro partition, repartitioned as ext4 with an 8 GB swap partition, and installed to the now empty partition. I rebooted, and no luck (kernel panic). From the SD card, I then tried "nix-build -A pkgs.uBootPinebookPro" as the README says and installed that to the eMMC. Again no luck. I then used nix-os enter to go into the partition, ran nixos-generate-config and put together a basic config while including the wip-pinebook-pro overlays, ran nixos-rebuild, then rebooted. Still broken. At this point I was about ready to give up, so I tried building the SD image from the SD card and flashing to the eMMC, and that worked.

Who knows what I was doing wrong, I'm just glad I got it working in the end!

[theotherjimmy]

Good point, I'll take out that step. I made a lot of mistakes throughout the process and tried a lot of things to fix the problem, that one may not have been needed.

I actually tried nixos-install from the SD card but couldn't get it to work. I deleted the Manjaro partition, repartitioned as ext4 with an 8 GB swap partition, and installed to the now empty partition. I rebooted, and no luck (kernel panic). From the SD card, I then tried "nix-build -A pkgs.uBootPinebookPro" as the README says and installed that to the eMMC. Again no luck. I then used nix-os enter to go into the partition, ran nixos-generate-config and put together a basic config while including the wip-pinebook-pro overlays, ran nixos-rebuild, then rebooted. Still broken. At this point I was about ready to give up, so I tried building the SD image from the SD card and flashing to the eMMC, and that worked.

Who knows what I was doing wrong, I'm just glad I got it working in the end!

I had those issues too, and then I realized that I had forgotten to include the PBP overlay in the configuration.nix of thee new system. Luckily, I kept the SD card around to be sure that I had a recovery image. Maybe you ran into a similar issue?

[_hg_]

It's possible. I definitely thought I had included it, but I may have overlooked that.