Skip to content

Commit

Permalink
docs: improve README
Browse files Browse the repository at this point in the history
  • Loading branch information
@Swarsel
Swarsel committed Dec 19, 2024
1 parent a0ade4d commit 9d12b9b
Showing 1 changed file with 107 additions and 54 deletions.
161 changes: 107 additions & 54 deletions .github/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,81 +3,134 @@

###### Disclaimer

You probably do not want to use this setup verbatim. This is made to fit my specific use cases, some of these settings will not make sense on other hosts. Also, nothing is ever stable here and changes are made on a daily basis.
You probably do not want to use this setup verbatim. This is made to fit my specific use cases, and I do not guarantee best practises everywhere. Changes are made on a daily basis.

That being said, there is a lot of general configuration that you *probably* can use without changes; if you only want to use this repository as a starting point for your own configuration, you should be fine. See below for more information. Also, if you see something that can be done more efficiently or better in general, please let me know! :)

# \~SwarselSystems\~

<img src="swarselsystems_preview.png"/>

| | |
|---------------|----------------------|
| **Shell:** | zsh |
| **DM:** | greetd |
| **WM:** | SwayFX |
| **Bar:** | Waybar |
| **Editor:** | Emacs |
| **Terminal:** | kitty |
| **Launcher:** | fuzzel |
| **Alerts:** | mako |
| **Browser:** | firefox |
| **Theme:** | city-lights |

The files that are possibly of biggest interest are found here:
| | |
|---------------|---------------------------------|
| **Shell:** | zsh |
| **DM:** | greetd |
| **WM:** | SwayFX |
| **Bar:** | Waybar |
| **Editor:** | Emacs |
| **Terminal:** | kitty |
| **Launcher:** | fuzzel |
| **Alerts:** | mako |
| **Browser:** | firefox |
| **Theme:** | city-lights (managed by stylix) |

## Overview

- Literate configuration for Nix and Emacs ([SwarselSystems.org](../SwarselSystems.org))
- Configuration based on flakes for personal hosts as well as servers on:
- NixOS
- home-manager only (no full NixOS)
- nix-darwin
- nix-on-droid
- Streamlined configuration pipeline:
- framework for [packages](https://github.com/Swarsel/.dotfiles/blob/main/pkgs/default.nix), [overlays](https://github.com/Swarsel/.dotfiles/blob/main/overlays/default.nix) [modules](https://github.com/Swarsel/.dotfiles/tree/main/modules) and modules
- dynamically generated host configurations
- limited local installer (no secrets handling) with a supported demo build
- fully autonomous remote deployment using [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) and [disko](https://github.com/nix-community/disko) (with secrets handling)
- Support for advanced features:
- Secrets handling using [sops-nix](https://github.com/Mic92/sops-nix) (pls don't pwn)
- Management of non-file-based secrets using private repo
- Full Yubikey support
- LUKS-encryption
- BTRFS-based [Impermanence](https://github.com/nix-community/impermanence)


## Documentation

If you are mainly interested in how I configured this system, check out this page:

[SwarselSystems literate configuration](https://swarsel.github.io/.dotfiles/)

This file will take you through my design process, in varying amounts of detail.

Otherwise, the files that are possibly of biggest interest are found here:

- [SwarselSystems.org](../SwarselSystems.org)
- [flake.nix](../flake.nix)
- [early-init.el](../programs/emacs/early-init.el)
- [init.el](../programs/emacs/init.el)

This is a nix flakes based setup that manages multiple hosts, including mixed (NixOS with home-manager as a submodule) as well as standalone home-manager configurations, also using some overlays etc. There even is a configuration for an Android build. It is all wrapped in literal configuration .org files, because that allows me to have easy access without actually having to remember where the specific configuration files are all located.

Have fun!
## Getting started

### General Nix tips
Sadly all things nix feel a bit underdocumented (even though it mostly is not). Below is a small list of tips that I thought could be helpful if you are new to the nix ecosystem:
### Demo configuration
If you just want to see if this configuration is for you, run this command on any system that has `nix` installed:

``` shell
nix run --experimental-features 'nix-command flakes' github:Swarsel/.dotfiles#install -- -u <YOUR_USERNAME>
```

This will install the `chaostheatre` configuration on your system, which is a de-facto mirror of my main configuration with secret-based settings removed. Please keep in mind that this limited installer will make local changes to this repository in order to be able to install it (otherwise the builder would fail at fetching my private secrets repository). As such, this should only be used to evaluate the system - if you want to use it longterm, you will need to create a fork and make some changes.

## Deployment

The deployment process for this configuration is mostly automated, there are only a few steps that are needed to be done manually:

0) Fork this flake, and write your own host config at `hosts/nixos/<YOUR_CONFIG_NAME>/default.nix` (you can use one of the other configurations as a template. Also see https://github.com/Swarsel/.dotfiles/tree/main/modules for a list of all additional options). At the very least, you should replace the `secrets/` directory with your own secrets and replace the SSH public keys with your own ones. I personally recommend to use the literate configuration and `org-babel-tangle-file` in Emacs, but you can also simply edit the separate `.nix` files.
1) Have a system with `nix` available booted (this does not need to be installed, i.e. you can use a NixOS installer image; a custom minimal installer ISO can be built by running `just iso` in the root of this repo)
2) Make sure that your Yubikey is plugged in or that you have your SSH key available (and configured)
3) Run

``` shell
nix run --experimental-features 'nix-command flakes' github:Swarsel/.dotfiles#install -- -n <CONFIGURATION_NAME> -d <TARGET_IP>
```

Alternatively (if you already have this configuration installed), you can also run `bootstrap -n <CONFIGURATION_NAME> -d <TARGET_IP>` (this runs the same program as the command above).
4) Follow the installers instructions:
- you will have to choose a disk encryption password (if you want that feature)
- you will have to confirm once that the target system has rebooted
- you will have to enter the root password once during the final system install
5) That should be it! The installer will take care of setting up disks, secrets, and the rest of the hardware configuration! You will still have to sign in manually to some webservices etc.

## General Nix tips
Below is a small list of tips that should be helpful no matter if you are new to the nix ecosystem:

- Once you have the experimental feature `nix-command` enabled, you can temporarily install any package using `nix shell nixpkgs#<PACKAGE_NAME>` - this can be e.g. useful if you accidentally removed home-manager from your packages on a non-NixOS machine.
- The `nix [...]` commands are generally very useful, more info can be found here: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix
- These links are your best friends:
- https://search.nixos.org/packages
- https://search.nixos.org/options
- https://nix-community.github.io/home-manager/options.html / https://mipmip.github.io/home-manager-option-search/
- Flake output reference: https://nixos-and-flakes.thiscute.world/other-usage-of-flakes/outputs
- or more general, the [NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/)
- Also useful is the [NixOS wiki](https://nixos.wiki/wiki/Main_Page), but some pages are outdated, so use with some care
- You can find public repositories with modules at https://nur.nix-community.org/ (you should check what you are installing however):
- I like to use this for rycee's firefox extensions: https://nur.nix-community.org/repos/rycee/
- When you are trying to setup a new configuration part, GitHub code search can really help you to find a working configuration.
- getting packages not maintained in a standard repository can be done in most cases easily with fetchFromGithub (https://ryantm.github.io/nixpkgs/builders/fetchers/)
- I have gathered some configuration snippets here: [Wiki.org](../Wiki.org). I will update this whenever I come across an interesting bit.

### Deployment
Below is a rough general guide to setup this system on a new NixOS host. **Again**, this is not recommended as this is a personal configuration. This also might not be the most efficient way to deploy a new Nix system, but it should work in the general case.

For a pure Home-Manager configuration, you need a few different steps. The biggest change is that you then want to call `home-manager --flake .#<your-username>@<your-hostname> switch` as the last step instead of `nixos-rebuild [...]`. A complete general guide for that case cannot really be given since you are most likely setting up the flake on a existing machine that already has a lot of configuration. If you are setting up a new system, I would recommend to use NixOS unless circumstances force you to use something else.

###### To do that:
1) adapt [SwarselSystems.org](../SwarselSystems.org)
1) adapt system specific options:
- Make a copy of "System/System Specific Configurations/TEMPLATE".
- Adapt all references to TEMPLATE to your host- and usernames etc - pay special attention to the header lines in each nix source block, i.e. the "#+begin_src nix [...] :tangle profiles/TEMPLATE/[...]" lines.

- Add the settings needed for your specific machine.
2) adapt flake:
- add a configuration block to "Noweb-Ref blocks/flake.nix/nixosConfigurations" (for example, you can copy one of the other blocks),
- adapt the paths to the files you chose to tangle to.
- adjust the "Inputs & Inputs@Outputs" and "let" sections if needed.
- (Use "[...]/homeConfigurations" instead if adding a home-manager config.)
2) Make sure Nix.org was actually tangled.
- **Beware:** This assumes you have access to a way of tangling an .org file (for most people this will mean having a working Emacs). If you do not have that, see below.
###### If you have no way of tangling .org files
In that case make a copy of the /.dotfiles/profiles/TEMPLATE folder and adapt each file manually according to the above, then edit the /.dotfiles/flake.nix manually.
##### Basic system setup
0) Make sure you have an internet connection (ethernet or for Wi-Fi e.g. call `nmcli`/`nmtui`)
1) `nix --experimental-features 'nix-command flakes' shell nixpkgs#git`
2) `git clone https://github.com/Swarsel/dotfiles.git`
3) `cp /etc/nixos/hardware-configuration.nix ~/.dotfiles/profiles/<YOUR_HOSTNAME>`
4) `git -C ~/.dotfiles add ~/dotfiles/profiles/<YOUR_HOSTNAME>`
5) `sudo nixos-rebuild --flake ~/.dotfiles/#<YOUR_HOSTNAME> boot`
6) Reboot.
- This build will take a while (mostly because it fully builds Emacs), so do not worry too much :)
- If you want to use sops-nix for secrets management, you need to provide your own key as well as a key for each host you are going to create. Then you need to adapt `.sops.yaml` to account for these keys and the directory where you are going to store the secrets. You can edit the secrets using `sops` using your key for authentication. You also need to edit the respective sections of the configuration to account for these locations.
- In case you get a dependency error for some of the `firefox-addons`, just comment out those specific extensions and try to uncomment them again a few days later. Sometimes when these packages are updated, the old .xpi file is deleted by the addon developer and the download link breaks. It is usually updated swiftly. If you do not want to wait, you can also package the addon yourself - there is one example in the files how this is done in general.
- getting packages at a different version than your target (or not packaged at all) can be done in most cases easily with fetchFromGithub (https://ryantm.github.io/nixpkgs/builders/fetchers/)
- you can easily install old revisions of packages using https://lazamar.co.uk/nix-versions/. You can conveniently spawn a shell with a chosen package available using `vershell <NIXPKGS_REVISION> <PACKAGE>`. Just make sure to pick a revision that has flakes enabled, otherwise you will need the legacy way of spawning the shell (see the link for more info)
- List of nerdfonts: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/data/fonts/nerd-fonts/manifests/fonts.json
- List of pre-commit-hooks: https://devenv.sh/reference/options/#pre-commithooks

## Attributionse, Acknowledgements, and Inspirations

These are in random order (also known as 'the order in which I discovered them')

- all the great people who have contributed code for the nix-community, with special mentions for (this list is unfairly incomplete):
- [guibou](https://github.com/guibou/)
- [Mic92](https://github.com/Mic92/sops-nix)
- [lassulus](https://github.com/lassulus)
- [danth](https://github.com/danth/)
- [LnL7](https://github.com/LnL7)
- [t184256](https://github.com/t184256)
- [bennofs](https://github.com/bennofs)
- the people who have inspired me with their configurations (sadly also highly incomplete):
- [theSuess](https://github.com/theSuess) with their [home-manager](https://code.kulupu.party/thesuess/home-manager)
- [hlissner](https://github.com/hlissner) with their [dotfiles](https://github.com/hlissner/dotfiles)
- [AntonHakansson](https://github.com/AntonHakansson) with their [nixos-config](https://github.com/AntonHakansson/nixos-config?tab=readme-ov-file)
- [NotAShelf](https://github.com/NotAShelf) with their [nyx](https://github.com/NotAShelf/nyx)
- [Misterio77](https://github.com/Misterio77) with their [nix-config](https://github.com/Misterio77/nix-config)
- [EmergentMind](https://github.com/EmergentMind) with their [nix-config](https://github.com/EmergentMind/nix-config)
- [librephoenix](https://github.com/librephoenix) with their [nixos-config](https://github.com/librephoenix/nixos-config)

If you feel that I forgot to pay you tribute for code that I used in this repository, please shoot me a message and I will fix it :)

0 comments on commit 9d12b9b

Please sign in to comment.