major refactor and doc update

This commit completely overhauls the documentation, uses the latest .default nix syntax, and overalls improves the usage experience
This commit is contained in:
Gabriel Fontes 2022-04-24 20:35:26 -03:00
parent f733955714
commit 29ec531cd9
No known key found for this signature in database
GPG key ID: 2E54EA7BFE630916
8 changed files with 295 additions and 150 deletions

179
README.md
View file

@ -2,72 +2,187 @@
This is a simple nix flake for getting started with NixOS + home-manager.
## Available versions:
- [Minimal](https://github.com/Misterio77/nix-starter-config/tree/minimal): Includes just a flake for referring to a `configuration.nix` and a `home.nix`.
- [Medium](https://github.com/Misterio77/nix-starter-config/tree/medium): Minimal + boilerplate for custom overlays, packages, and nixos/home-manager modules.
- [Complete](https://github.com/Misterio77/nix-starter-config/tree/complete): Medium + hosts and users are located in their own directories.
## What this provides
- NixOS configuration on `configuration.nix`, accessible via `nixos-rebuild --flake`
- Home-manager configuration on `home.nix`, accessible via `home-manager --flake`
- Basic boilerplate for adding custom packages (under `pkgs`) and overlays (under `overlays`). Acessible on your system, home config, as well as `nix build .#package-name`
- Boilerplate for custom NixOS (`modules/nixos`) and home-manager (`modules/home-manager`) modules
- Dev shell for bootstrapping, accessible via `nix develop`
- NixOS configuration on `nixos/configuration.nix`, accessible via
`nixos-rebuild --flake`
- Home-manager configuration on `home-manager/home.nix`, accessible via
`home-manager --flake`
- Basic boilerplate for adding custom packages (under `pkgs`) and overlays
(under `overlays`). Acessible on your system, home config, as well as `nix
build .#package-name`
- Boilerplate for custom NixOS (`modules/nixos`) and home-manager
(`modules/home-manager`) modules
## Getting started
Assuming you have a basic NixOS installation up and running:
Assuming you have a basic NixOS booted up (either live or installed, anything
works). Here's [a link to the latest NixOS downloads, just for
you](https://nixos.org/download#download-nixos)
### The repo
- [Install git](https://nixos.wiki/wiki/git)
- Clone this repo to somewhere acessible (i usually have a `/dotfiles` folder for this)
- Add stuff you currently have on `/etc/nixos/configuration.nix` to `configuration.nix`, and `/etc/nixos/hardware-configuration.nix` to `hardware-configuration.nix`
- If you're already using home-manager, add your stuff from `~/.config/nixpkgs/home.nix` to `home.nix`
- Take a look at `flake.nix`, filling out stuff marked by `TODO`s
- Create a remote repo (github, gitlab, sr.ht, etc) and push your changes for safekeeping
- Clone this repo to somewhere acessible (somewhere in your home directory is
good enough)
- Add stuff you currently have on `/etc/nixos/` to `nixos` (usually
`configuration.nix` and `hardware-configuration.nix`, when you're starting
out).
- The included file has some options you might want, specially if you don't
have a configuration ready. Make sure you have generated your own
`hardware-configuration.nix`; if not, just mount your partitions to
`/mnt` and run: `nixos-generate-config --root /mnt`.
- If you're already using home-manager, add your stuff from `~/.config/nixpkgs`
to `home-manager` (probably `home.nix`).
- I also include one with some simple options if you need. Feel free to
ignore this step if you don't want to use home-manager just yet.
- Take a look at `flake.nix`, making sure to fill out anything marked with
FIXME (required) or TODO (usually tips or optional stuff you might want)
- Create a remote repo (github, gitlab, sr.ht, etc) and push your changes for
safekeeping (or at least copy your directory to somewhere safe, specially if you're on a installation medium)
### Bootstrapping
- Run `nix develop --experimental-features "nix-command flakes"` to bootstrap into flake-enabled nix and home-manager.
- Run `sudo nixos-rebuild switch --flake .` to apply system configuration
- Run `home-manager switch --flake .` to apply home configuration
- Reboot!
To get everything up and running, you need flake-enabled nix and home-manager.
First off, check your nix version using `nix --version`.
#### Version < 2.4
Bummer, your nix version does not support flakes. But fear not!
You _don't_ need to mess around with channels to get up and running.
Just run:
```bash
nix-shell
```
Wow, that was easy. Our `shell.nix` file will detect you can't evaluate (nor
lock) the flake, and will grab `nix` and `home-manager` from the latest
`nixos-unstable` versions, just for you.
Once you're bootstrapped, remember to run `nix flake lock` and commit the
newly-created `flake.lock` into your repository, this will make future
bootstraps reproductible.
#### Version >= 2.4
Congrats, your nix version supports flakes! It's just hidden behind a feature flag.
You can bootstrap with:
```bash
nix develop .#default
```
This should generate a `flake.lock`. Remember to commit it, as this will make
future bootstraps reproductible.
### Usage
- Run `sudo nixos-rebuild switch --flake .#hostname` to apply your system
configuration.
- If you're still on a live installation medium, run `nixos-install --flake
.#hostname` instead, and reboot. Ignore the home-manager step for now.
- Run `home-manager switch --flake .#username@hostname` to apply your home
configuration.
And that's it, really! You're ready to have fun with your configurations using
the latest and greatest nix3 flake-enabled command UX.
## What next?
### User password and secrets
For people fresh from installation: Unless you used `--no-root-passwd`,
`nixos-install` prompted you for a root password. Use it to log into the root
account, set your own account's password imperatively with `passwd`, and
disable root login (`sudo passwd -l root`). You can also use `--no-root-passwd`
and instead set `initialPassword` for your user, for a temporary password upon
install.
If you don't want to set your password imperatively, you can also use
`passwordFile` for safely and declaratively setting a password from a file
outside the nix store.
There's also more advanced options for secret management, including some that
can include them (encrypted) into your config repo and/or nix store, be sure to
check them out if you're interested.
### Include files using home-manager
Besides just adding packages to your environment, home-manager can also manage
your dotfiles. I strongly recommend you do, it's awesome!
For full nix goodness, check out the home-manager modules with `man
home-configuration.nix`. Using them, you'll be able to fully configure any
usual dotfile with nix syntax and abstractions (including your own powerful
modules and functions).
Alternatively, if you're still not ready to rewrite all your configs in nix
syntax, there's home-manager options (such as `xdg.configFile`) for including
files from your nix-config repository into your config directories. Add your
existing dotfiles to this repo and try it out!
### Try opt-in persistance
You might have noticed that there's impurity in your NixOS system, in the form
of configuration files and other cruft your system generates when running. What
if you change them in a whim? Boom, your system is not fully reproductible
anymore.
You can instead fully delete your `/` and `/home` on every boot! Nix is okay
with a empty root on boot, and will happily reapply your configurations (as
long as `/nix` is intact).
There's two main approaches to this: mount a `tmpfs` (RAM disk) to `/`, or
(using a filesystem such as btrfs or zfs) mount a blank snapshot and reset it
on boot.
For stuff that can't be managed through nix (such as games downloaded from
steam, or logs), use [impermanence](https://github.com/nix-community/impermanence)
for mounting stuff you to keep to a separate partition/volume (such as
`/nix/persist` or `/persist`). This makes everything vanish by default, and you
can keep track of what you specifically asked to be kept.
## How to's
### Customize your NixOS configuration
Use the `configuration.nix` file.
Use the `nixos/configuration.nix` file.
For a list of options, see `man configuration.nix`. Also see [the manual](https://nixos.org/manual/nixos/stable/index.html#ch-configuration).
For a list of options, see `man configuration.nix`. Also see [the
manual](https://nixos.org/manual/nixos/stable/index.html#ch-configuration).
### Customize your home-manager configuration
Use the `home.nix` file.
Use the `home-manager/home.nix` file.
For a list of options, see `man home-configuration.nix`. Also see [the manual](https://rycee.gitlab.io/home-manager/index.html#ch-usage).
For a list of options, see `man home-configuration.nix`. Also see [the
manual](https://rycee.gitlab.io/home-manager/index.html#ch-usage).
### Adding packages
Create a folder inside `pkgs`, and add a `default.nix` file containing a derivation. Be sure to also `callPackage` them on `pkgs/default.nix`.
Create a folder with the package name inside `pkgs`, and add a `default.nix`
file containing a derivation. Be sure to also `callPackage` them on
`pkgs/default.nix`.
See [the manual](https://nixos.org/manual/nixpkgs/stable/).
### Adding overlays
Use the `overlays/default.nix` file. If it gets too big, feel free to split it up.
Use the `overlay/default.nix` file.
If you're applying patches, i recommend you keep the patches on the `overlays` folder as well.
If you're applying patches, you can keep them on the `overlay` folder as well.
See [the wiki article](https://nixos.wiki/wiki/Overlays).
### Adding your own modules
Create a file for them on either `modules/nixos` or `modules/home-manager`. Be sure to also add them to the listing at `modules/nixos/default.nix` or `modules/home-manager/default.nix`.
Create a file for them on either `modules/nixos` or `modules/home-manager`. Be
sure to also add them to the listing at `modules/nixos/default.nix` or
`modules/home-manager/default.nix`.
See [the wiki article](https://nixos.wiki/wiki/Module).
### Adding more hosts or users, or multiple files
If you're starting to manage more than one host or user (or splitting up a big configuration in multiple files), you might want to create a `hosts` and/or `users` folder, and move your configs there. Be sure to change the path on `flake.nix` as well.
### Adding more hosts or users
You can organize them by hostname and username on `nixos` and `home-manager`
directories, be sure to also add them to `flake.nix`

110
flake.nix
View file

@ -2,95 +2,95 @@
description = "You new nix config";
inputs = {
# Utilities for building flakes
utils.url = "github:numtide/flake-utils";
# Core nix flakes
# Nixpkgs
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
hardware.url = "github:nixos/nixos-hardware";
# Home manager flake
# Home manager
home-manager.url = "github:nix-community/home-manager";
home-manager.inputs.nixpkgs.follows = "nixpkgs";
# Extra community flakes
# Add any cool flakes you need
# Utilities for building our flake
flake-utils.url = "github:numtide/flake-utils";
# Extra flakes for modules, packages, etc
hardware.url = "github:nixos/nixos-hardware"; # Convenience modules for hardware-specific quirks
# nur.url = "github:nix-community/NUR"; # User contributed pkgs and modules
# impermanence.url = "github:riscadoa/impermanence"; # Utilities for opt-in persistance
# nix-colors.url = "github:misterio77/nix-colors"; # Color schemes for usage with home-manager
# impermanence.url = "github:riscadoa/impermanence"; # Utilities for opt-in persistance
# TODO: Add any other flakes you need
};
outputs = { self, nixpkgs, home-manager, utils, ... }@inputs: {
# Overlayed packages
overlay = (import ./overlays);
# This repo's overlay plus any other overlays you use
# If you want to use packages from flakes that are not nixpkgs (such as NUR), add their overlays here.
overlays = [
self.overlay
# nur.overlay
];
outputs = { nixpkgs, home-manager, flake-utils, ... }@inputs:
let
# Bring some functions into scope (from builtins and other flakes)
inherit (builtins) attrValues;
inherit (flake-utils.lib) eachSystemMap defaultSystems;
inherit (nixpkgs.lib) nixosSystem;
inherit (home-manager.lib) homeManagerConfiguration;
eachDefaultSystemMap = eachSystemMap defaultSystems;
in
rec {
# TODO: If you want to use packages exported from other flakes, add their overlays here.
# They will be added to your 'pkgs'
overlays = {
default = import ./overlay; # Our own overlay
# nur = nur.overlay
};
# System configurations
# Accessible via 'nixos-rebuild --flake'
# Accessible via 'nixos-rebuild'
nixosConfigurations = {
# TODO: Replace with your hostname
cool-computer = nixpkgs.lib.nixosSystem {
# FIXME: Replace with your hostname
cool-computer = nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
# Adds your overlay and packages to nixpkgs
{ nixpkgs.overlays = self.overlays; }
# Adds your custom nixos modules
# >> Main NixOS configuration file <<
./nixos/configuration.nix
# Add your custom NixOS modules
./modules/nixos
# Add overlays
{ nixpkgs.overlays = attrValues overlays; }
];
# Pass our flake inputs into the config
# Make our inputs available to the config (for importing modules)
specialArgs = { inherit inputs; };
};
};
# Home configurations
# Accessible via 'home-manager --flake'
# Accessible via 'home-manager'
homeConfigurations = {
# TODO: Replace with your username@hostname
"you@cool-computer" = home-manager.lib.homeManagerConfiguration rec {
# TODO: Replace with your username
# FIXME: Replace with your username@hostname
"you@cool-computer" = homeManagerConfiguration rec {
# FIXME: Replace with your username
username = "you";
homeDirectory = "/home/${username}";
system = "x86_64-linux";
configuration = ./home.nix;
# >> Main home-manager configuration file <<
configuration = ./home-manager/home.nix;
extraModules = [
# Adds your overlay and packages to nixpkgs
{ nixpkgs.overlays = self.overlays; }
# Adds your custom home-manager modules
# Add your custom home-manager modules
./modules/home-manager
# Add overlays
{ nixpkgs.overlays = attrValues overlays; }
];
# Pass our flake inputs into the config
# Make our inputs available to the config (for importing modules)
extraSpecialArgs = { inherit inputs; };
};
};
}
// utils.lib.eachDefaultSystem (system:
let
pkgs = import nixpkgs { inherit system; overlays = self.overlays; };
nix = pkgs.writeShellScriptBin "nix" ''
exec ${pkgs.nixFlakes}/bin/nix --experimental-features "nix-command flakes" "$@"
'';
hm = home-manager.defaultPackage."${system}";
in
{
# Your custom packages, plus nixpkgs and overlayed stuff
# Accessible via 'nix build .#example' or 'nix build .#nixpkgs.example'
packages = {
nixpkgs = pkgs;
} // (import ./pkgs { inherit pkgs; });
# Devshell for bootstrapping plus editor utilities (fmt and LSP)
# Packages
# Accessible via 'nix build'
packages = eachDefaultSystemMap (system:
# Propagate nixpkgs' packages, with our overlays applied
import nixpkgs { inherit system; overlays = attrValues overlays; }
);
# Devshell for bootstrapping
# Accessible via 'nix develop'
devShell = pkgs.mkShell {
buildInputs = with pkgs; [ nix nixfmt rnix-lsp hm ];
};
devShells = eachDefaultSystemMap (system: {
default = import ./shell.nix { pkgs = packages.${system}; };
});
};
}

View file

@ -2,69 +2,74 @@
# Use this to configure your system environment (it replaces /etc/nixos/configuration.nix)
{ inputs, lib, config, pkgs, ... }: {
imports = [
# If you want to use modules from other flakes (such as nixos-hardware), use something like:
# inputs.hardware.nixosModules.common-cpu-amd
# inputs.hardware.nixosModules.common-ssd
# It's strongly recommended you take a look at
# https://github.com/nixos/nixos-hardware
# and import modules relevant to your hardware.
# Import your generated hardware configuration
# Import your generated (nixos-generate-config) hardware configuration
./hardware-configuration.nix
# Feel free to split up your configuration and import pieces of it here.
# You can also split up your configuration and import pieces of it here.
];
# This will add your inputs as registries, making operations with them (such
# as nix shell nixpkgs#name) consistent with your flake inputs.
nix.registry = lib.mapAttrs' (n: v: lib.nameValuePair n { flake = v; }) inputs;
# Will activate home-manager profiles for each user upon login
# This is useful when using ephemeral installations
environment.loginShellInit = ''
[ -d "$HOME/.nix-profile" ] || /nix/var/nix/profiles/per-user/$USER/home-manager/activate &> /dev/null
'';
nix = {
# Make sure we have at least nix 2.4
# TODO: You can remove me if you're using NixOS 22.05+
package = pkgs.nixFlakes;
# Enable flakes and new 'nix' command
extraOptions = ''
experimental-features = nix-command flakes
'';
autoOptimiseStore = true;
};
# Remove if you wish to disable unfree packages for your system
nixpkgs.config.allowUnfree = true;
# FIXME: Add the rest of your current configuration
# TODO: Set your hostname
networking.hostName = "cool-computer";
# TODO: This is just an example, be sure to use whatever bootloader you prefer
boot.loader.systemd-boot.enable = true;
# TODO: Configure your system-wide user settings (stuff on the user
# environment should instead go to home.nix)
# TODO: Configure your system-wide user settings (groups, etc), add more users as needed.
users.users = {
# TODO: Replace with your username
# FIXME: Replace with your username
you = {
isNormalUser = true;
openssh.authorizedKeys.keys = [
# TODO: Add your SSH public key(s) here, if you plan on using SSH to connect
];
# Be sure to add any other groups you need
# TODO: Be sure to add any other groups you need (such as networkmanager, audio, docker, etc)
extraGroups = [ "wheel" ];
};
};
# This setups SSH for the system (with SSH keys ONLY). Feel free to remove if you don't need it.
# This setups a SSH server. Very important if you're setting up a headless system.
# Feel free to remove if you don't need it.
services.openssh = {
enable = true;
passwordAuthentication = false;
# Forbid root login through SSH.
permitRootLogin = "no";
# Use keys only. Remove if you want to SSH using password (not recommended)
passwordAuthentication = false;
};
# Remove if you wish to disable unfree packages for your system
nixpkgs.config.allowUnfree = true;
# Enable flakes and new 'nix' command
nix = {
package = pkgs.nixFlakes;
extraOptions = ''
experimental-features = nix-command flakes
'';
autoOptimiseStore = true;
};
# This will make all users activate their home-manager profile upon login, if
# it exists and is not activated yet. This is useful for setups with opt-in
# persistance, avoiding having to manually activate every reboot.
environment.loginShellInit = ''
[ -d "$HOME/.nix-profile" ] || /nix/var/nix/profiles/per-user/$USER/home-manager/activate &> /dev/null
'';
# This will add your inputs as registries, making operations with them
# consistent with your flake inputs.
nix.registry = lib.mapAttrs' (n: v:
lib.nameValuePair (n) ({ flake = v; })
) inputs;
}

View file

@ -1,7 +1,8 @@
# Your overlays should go here (https://nixos.wiki/wiki/Overlays)
# Your overlays go here (see https://nixos.wiki/wiki/Overlays)
final: prev: {
# example = prev.example.overrideAttrs (oldAttrs: rec {
# ...
# });
# This line adds our custom packages into the overlay.
} // import ../pkgs { pkgs = final; }
# This line adds your custom packages into the overlay.

View file

@ -1,3 +0,0 @@
# This is a package. You can use the same format any package on nixpkgs uses.
# Example: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/applications/misc/hello/default.nix
{}

27
shell.nix Normal file
View file

@ -0,0 +1,27 @@
# Shell for bootstrapping flake-enabled nix and home-manager, from any nix version
{ pkgs ? let
system = builtins.currentSystem or "Unknown system";
nixpkgs =
if builtins.pathExists ./flake.lock
then
# If we have a lock, fetch locked nixpkgs
let lock = builtins.fromJSON (builtins.readFile ./flake.lock).nodes.nixpkgs.locked;
in
fetchTarball {
url = "https://github.com/nixos/nixpkgs/archive/${lock.rev}.tar.gz";
sha256 = lock.narHash;
}
else
# If not (probably because not flake-enabled), fetch nixos-unstable impurely
fetchTarball {
url = "https://github.com/nixos/nixpkgs/archive/nixos-unstable.tar.gz";
};
in
import nixpkgs { inherit system; }
, ...
}:
pkgs.mkShell {
nativeBuildInputs = with pkgs; [ nix home-manager git ];
}