kickstart.nix

Kickstart your Nix environments.

Guides

• Setup Home Manager
• Setup NixOS
• Setup macOS

Templates

• Languages
  • Bash
  • C++ (cmake)
  • Go (module)
  • Go (package)
  • Lua (application)
  • Node.js (backend)
  • OCaml
  • Python (application)
  • Python (package)
  • Rust
• Systems
  • macOS (desktop)
  • NixOS (desktop)
  • NixOS (minimal)

Guides

Setup Home Manager

1. Install nixpkgs with official script:

Note

The offical docs suggest using daemon mode to install with this approach. Nix currently does not support SELINUX enabled.

sh <(curl -L https://nixos.org/nix/install) --daemon

2. Edit /etc/nix/nix.conf to enable the following settings:

experimental-features = nix-command flakes

3. Create a new directory for your flake.nix configuration:

mkdir -p ~/kickstart.nix
cd ~/kickstart.nix

4. Using nix flake init generate the kickstart.nix template locally:

nix flake init -t github:ALT-F4-LLC/kickstart.nix#home-manager

5. Update following value(s) in flake.nix configuration:

homeManagerModule = import ./module/home-manager.nix {
  homeDirectory = throw "<enter homeDirectory in flake.nix>"; # TODO: home directory of the user
  username = throw "<enter username in flake.nix>"; # TODO: username of the user
};

6. Run home-manager from nixpkgs to build and switch environments:

Important

This template supports the following systems: aarch64-darwin, aarch64-linux, x86_64-darwin and x86_64-linux.

# for ARM systems running macOS
nix run nixpkgs#home-manager -- build --flake .#aarch64-darwin
nix run nixpkgs#home-manager -- switch --flake .#aarch64-darwin

# for ARM systems running Linux
nix run nixpkgs#home-manager -- build --flake .#aarch64-linux
nix run nixpkgs#home-manager -- switch --flake .#aarch64-linux

# for Intel systems running macOS
nix run nixpkgs#home-manager -- build --flake .#x86_64-darwin
nix run nixpkgs#home-manager -- switch --flake .#x86_64-darwin

# for Intel systems running Linux
nix run nixpkgs#home-manager -- build --flake .#x86_64-linux
nix run nixpkgs#home-manager -- switch --flake .#x86_64-linux

Congrats! You've setup Home Manager on your existing operating system!

Be sure to explore the files below to get started customizing:

• module/home-manager.nix for Home Manager related settings
• flake.nix for flake related settings

Setup macOS

1. Install nixpkgs with official script:

sh <(curl -L https://nixos.org/nix/install)

2. Install nix-darwin with official steps:

nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A installer
./result/bin/darwin-installer

3. Answer the following with y to edit your default configuration.nix file:

Would you like to edit the default configuration.nix before starting? [y/n] y

4. Add the following to configuration.nix to enable nix-command and flakes features:

nix.settings.experimental-features = [ "nix-command" "flakes" ];

5. Answer the following with y to setup <darwin> in nix-channel (though it won't be used):

Would you like to manage <darwin> with nix-channel? [y/n] y

6. Create a new directory for your flake.nix configuration:

mkdir -p ~/kickstart.nix
cd ~/kickstart.nix

7. Using nix flake init generate the kickstart.nix template locally:

nix flake init -t github:ALT-F4-LLC/kickstart.nix#darwin

8. Update the following value(s) in flake.nix configuration:

let
    username = throw "<username>"; # TODO: replace with user name and remove throw 
in

9. Switch to kickstart.nix environment for your system with flake configuration:

darwin-rebuild switch --flake ".#aarch64" # M Series Chipsets
darwin-rebuild switch --flake ".#x86_64" # Intel Chipsets

Congrats! You've setup Nix with Home Manager on macOS!

Be sure to explore the files below to get started customizing:

• system/darwin.nix for all nix-darwin related settings
• module/configuration.nix for Nix related settings
• module/home-manager.nix for Home Manager related settings
• flake.nix for flake related settings

Setup NixOS

1. Install NixOS using the latest ISO image for your system.

2. Add the following to /etc/nixos/configuration.nix to enable nix-command and flakes features:

nix.extraOptions = "experimental-features = nix-command flakes";

3. Update you system to reflect the changes:

sudo nixos-rebuild test
sudo nixos-rebuild switch

4. Create a new directory for your flake.nix configuration:

mkdir -p ~/kickstart.nix
cd ~/kickstart.nix

7. Using nix flake init generate the kickstart.nix template of your choice locally:

nix flake init -t github:ALT-F4-LLC/kickstart.nix#nixos-desktop
nix flake init -t github:ALT-F4-LLC/kickstart.nix#nixos-minimal

6. Update the following value(s) in flake.nix configuration:

• For desktop flake template:

let
    nixos-system = import ./system/nixos.nix {
        inherit inputs;
        username = throw "<username>"; # REQUIRED: replace with user name and remove throw
        password = throw "<password>"; # REQUIRED: replace with password and remove throw
        desktop = "gnome"; # optional: "gnome" by default, or "plasma5" for KDE Plasma
    };
in

• For minimal flake template:

let
    nixos-system = import ./system/nixos.nix {
        inherit inputs;
        username = throw "<username>"; # REQUIRED: replace with user name and remove throw
        password = throw "<password>"; # REQUIRED: replace with password and remove throw
    };
in

7. Switch to kickstart.nix environment for your system with flake configuration:

Important

We use --impure due to how /etc/nixos/hardware-configuration.nix is generated and stored on the system after installation. To avoid using this flag, copy hardware-configuration.nix file locally and replace import in the template (see example here).

• For aarch64 platforms:

sudo nixos-rebuild test --flake ".#aarch64" --impure # M Series Chipsets
sudo nixos-rebuild switch --flake ".#aarch64" --impure # M Series Chipsets

• For x86_64 platforms:

sudo nixos-rebuild test --flake ".#x86_64"  --impure # Intel Chipsets
sudo nixos-rebuild switch --flake ".#x86_64" --impure # Intel Chipsets

Congrats! You've setup NixOS with Home Manager!

Be sure to explore the files below to get started customizing:

• module/configuration.nix for more NixOS system related settings
• module/home-manager.nix for Home Manager related settings
• system/nixos.nix for NixOS system related settings
• flake.nix for flake related settings

Languages

Bash

Used for Bash scripts.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#bash

C++ (cmake)

Used for C++ projects using CMake as a build system.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#cpp-cmake

Go (module)

Used for modern Go apps setup with go.mod system. To build legacy Go apps, use go-pkg template.

Important

Be sure to update go.mod with proper repository after running init command.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#go-mod

Go (package)

Used for legacy Go apps not setup with go.mod system. To build modern Go apps, use go-mod template.

Important

Be sure to update deps.nix with vendor dependencies after running init command (read more).

nix flake init -t github:ALT-F4-LLC/kickstart.nix#go-pkg

Lua (application)

Used for Lua script applications. This template creates a shell script wrapper which executes your Lua code. See flake.nix for more.

Note

We wrap Lua because we are using an interpreted language which requires both binary and code to run. This is similar to console scripts in the python-app template.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#lua-app

Node.js (backend)

Used for Node.js backend applications. The template builds using npm, and does not assume you use TypeScript.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#nodejs-backend

To update your dependencies, install/upgrade them as normal via NPM, then use the prefetch-npm-deps package from nixpkgs to generate a new npmDepsHash value for packages.default in the Flake.

$ nix shell 'nixpkgs#prefetch-npm-deps' -c prefetch-npm-deps package-lock.json
...
sha256-nTTzkQEdnwWEQ/3uy8hUbPsRvzM53xuoJHoQhR3E/zk=

Tip

To add TypeScript, install it with npm install --save-dev typescript, add a build script to package.json that calls tsc, and then remove dontNpmBuild = true; from packages.default in your Flake.

OCaml

Used for OCaml applications.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#ocaml

Python (application)

Used for runnable Python apps setup with setup.py and includes wrapped console scripts that can be executed from CLI. To build re-useable Python packages, use python-pkg template.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#python-app

Python (package)

Used for Python packages setup with setup.py that can be re-used within other Nix-built applications or packages. To build runnable Python apps, use python-app template.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#python-pkg

Rust

Used for Rust applications.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#rust

Systems

macOS (desktop)

macOS template allows you to run Nix tools on your native Mac hardware.

Tip

This setup is ideal for developers already using macOS.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#darwin

NixOS (desktop)

NixOS desktop template includes base operating system with GNOME (default) windows manager included. You can also use plasma5 by changing desktop value in flake.nix file.

Tip

This setup is ideal for getting started moving to NixOS as your main desktop.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#nixos-desktop

NixOS (minimal)

NixOS minimal template includes base operating system without any windows manager.

Tip

This setup is ideal for servers and other headless tasks.

nix flake init -t github:ALT-F4-LLC/kickstart.nix#nixos-minimal