What's the page for setting up a NixOS configuration.nix file? Flakes or no? Home manager?

[willhansen]

Observations

I've been getting into NixOS over the past week (big fan of declarative system configuration).

The latest hurdle I've run into is looking for a simple example of a system configuration based on flakes rather than channels.

• As I understand it, flakes are "the way to go".

So, let's say I've just installed nixos. Now I need a configuration to start building off of. How do I find this?

The path that I actually followed:

On the NixOS wiki (I know this repo doesn't control this. Bear with me). The discovery path is:

1. Go to the NixOS wiki (https://nixos.wiki/)
2. Click on the top-left-most link in the page.
   • The most obvious starting point of the entire wiki.
   • 
3. I scroll down a little, and I get a simple example configuration file.
   • I can work with this, and immediately start adding to it to configure my system.
   • (Note that this page has absolutely no mention of flakes)
   • 
4. I learn about the home manager, and have to figure out how to set that up on my own
5. I learn about flakes, and have to figure out how to make my configuration use that on my own
   • After far too long searching, looking at over-complicated and maybe-outdated other configuration files, I eventually found what I needed halfway down the Flakes page of the wiki (which isn't even linked on the wiki's front page)
   • 

---

Then I learn that the main contact point for learning isn't even supposed to be the wiki. It's nix.dev.

• Nix.dev is tracked with git. I like this.
• There is no link to nix.dev on the front page of the wiki (that I could see)
• There is no link to the wiki from the front page of nix.dev (that I could see)

The path that I officially "should have" followed:

The discovery path on nix.dev:
(Keep in mind I'm looking for a simple NixOS configuration.nix to base my configuration around)

1. Go to nix.dev
2. Click the top-left-most link on the page
   • "Tutorials", looks like a good place to start
   • 
3. Take a look at the list
   • 
   • The first two sections aren't NixOS, so aren't relevant to me.
   • "Building and running Docker images" - Not using docker
   • "Building a bootable ISO image" - I already have NixOS installed, don't need an ISO
   • "Continuous Integration with GitHub Actions" - I need basic setup not github CI
   • "Deploying NixOS using Terraform" - I barely even know what terraform is
   • "Installing NixOS on a Raspberry Pi" - Definitely not raspberry pi
   • "Integration testing using virtual machines (VMs)" - I'm not using integration testing yet
   • The first half of the "NixOS virtual machines" page actually does have a very helpful example configuration, but the title has nothing to do with configuration or setup, so I'd probably miss it. (This config also does not mention flakes)
   • "References" - Here we go! This has got to have a reference config file!
     • There's a link that looks right: "NixOS Manual: NixOS Configuration.", but it's a dense manual page. Not the simple quick example I'm looking for.
4. Go back to the main page
5. Look in the "References". I'm looking for a configuration file to use as reference. This makes sense
   • It's all dense manual pages.
6. Back to main page. Maybe the "Recipes" page this time?
   • I'm seeing language features
   • The NixOS FAQ section likewise does not have an example configuration
7. "Concepts" just has flakes stuff. I haven't even found an example configuration file yet.

Problem

• Nix.dev has no starting point for NixOS configuration. To say nothing of one using flakes and home manager.

Approaches

• The front page needs a link to at least one simple example configuration file. Preferably a heavily commented one

Willing to help?

Here's my config I've assembled over the past week.

flake.nix
This is symlinked to /etc/nixos/flake.nix

{
  description = "Main system configuration flake";
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
    home-manager.url = "github:nix-community/home-manager/release-23.05";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = inputs@{ self, nixpkgs, ...}: {
    nixosConfigurations.nixos-server = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      specialArgs = inputs;
      modules = [ ./configuration.nix ];
    };
  };
}

configuration.nix

• Place in same folder as flake.nix.
• No symlink required.
• I removed my public keys and hashed passwords, replaced with "<[REDACTED]>".
• apply the configuration with sudo nixos-rebuild switch
• The files ./hardware-configuration.nix and ./networking.nix files were generated by nixos-infect. I do not understand them, so I did not include them.

{ pkgs, config, home-manager, ... }:                                                                                                                                                                                                
let                                                                                                                                                                                                                                 
                                                                                                                                                                                                                                    
desktop_key =    <[REDACTED]>                                                                                                                                                                                                                                                               
                                                                                                                                                                                                                                    
phone_key = <[REDACTED]>                                                 
                                                                                                                                                                                                                                    
#home-manager = builtins.fetchTarball "https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz";                                                                                                                 
#home-manager = builtins.fetchTarball "https://github.com/nix-community/home-manager/archive/master.tar.gz";                                                                                                                        
                                                                                                                                                                                                                                    
in                                                                                                                                                                                                                                  
{                                                                                                                                                                                                                                   
                                                                                                                                                                                                                                    
        imports = [                                                                                                                                                                                                                 
                ./hardware-configuration.nix                                                                                                                                                                                        
                ./networking.nix # generated at runtime by nixos-infect                                                                                                                                                             
                home-manager.nixosModules.default                                                                                                                                                                                   
        ];                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
        # https://nixos.wiki/wiki/FAQ/When_do_I_update_stateVersion                                                                                                                                                                 
        system.stateVersion = "23.05";                                                                                                                                                                                              
                                                                                                                                                                                                                                    
        boot.tmp.cleanOnBoot = true;                                                                                                                                                                                                
        zramSwap.enable = true;                                                                                                                                                                                                     
        networking.hostName = "nixos-server";                                                                                                                                                                                       
        networking.domain = "";                                                                                                                                                                                                     
        services.openssh.enable = true;                                                                                                                                                                                             
                                                                                                                                                                                                                                    
        users.defaultUserShell = pkgs.zsh;                                                                                                                                                                                          
        environment.shells = [ pkgs.zsh ];                                                                                                                                                                                          
                                                                                                                                                                                                                                    
        security.sudo = {                                                                                                                                                                                                           
                enable = true;                                                                                                                                                                                                      
                wheelNeedsPassword = true;                                                                                                                                                                                          
        };                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
        nix.settings = {                                                                                                                                                                                                            
                auto-optimise-store = true;                                                                                                                                                                                         
                experimental-features = [ "nix-command" "flakes" ];                                                                                                                                                                 
        };                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
        users.mutableUsers = false;                                                                                                                                                                                                 
        users.users = {                                                                                                                                                                                                             
                root.openssh.authorizedKeys.keys = [ desktop_key ];                                                                                                                                                                 
                will = {                                                                                                                                                                                                            
                        isNormalUser = true;                                                                                                                                                                                        
                        home = "/home/will";                                                                                                                                                                                        
                        extraGroups = [ "wheel" ];                                                                                                                                                                                  
                        openssh.authorizedKeys.keys = [ desktop_key phone_key ];                                                                                                                                                    
                                                                                                                                                                                                                                    
                        hashedPassword = <[REDACTED]>                                                                                                                                                       
                                                                                                                                                                                                                                    
                };                                                                                                                                                                                                                  
                                                                                                                                                                                                                                    
        };                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
        environment.systemPackages = with pkgs; [                                                                                                                                                                                  
                mkpasswd                                                                                                                                                                                                            
                ripgrep                                                                                                                                                                                                             
                bat # cat (or ls?) replacement                                                                                                                                                                                      
                exa # ls replacement                                                                                                                                                                                                
                chafa # display images in terminal                                                                                                                                                                                  
                tealdeer # for tldr                                                                                                                                                                                                 
                rustup                                                                                                                                                                                                              
                bottom # htop replacement                                                                                                                                                                                           
                fd                                                                                                                                                                                                                  
                zoxide # cd replacement                                                                                                                                                                                             
                sd                                                                                                                                                                                                                  
                kalker # calculator                                                                                                                                                                                                 
        ];                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
        programs = {                                                                                                                                                                                                                
                                                                                                                                                                                                                                    
                                                                                                                                                                                                                                    
                zsh = {                                                                                                                                                                                                             
                        enable = true;                                                                                                                                                                                              
                        shellAliases = {                                                                                                                                                                                            
                                ll = "ls -l";                                                                                                                                                                                       
                                update = "sudo nixos-rebuild switch";                                                                                                                                                               
                                howbig = "du -hs * | sort -hr";                                                                                                                                                                     
                                big = "howbig";                                                                                                                                                                                     
                        };                                                                                                                                                                                                          
                        # TODO: need this?                                                                                                                                                                                          
                        #history = {                                                                                                                                                                                                
                        #size = 10000;                                                                                                                                                                                              
                        #path = "${config.xdg.dataHome}/zsh/history";                                                                                                                                                               
                        #};                                                                                                                                                                                                         
                        ohMyZsh = {
                                enable = true;
                                plugins = [ "git" ];
                                theme = "gnzh";
                        };
                };

                fzf = {
                        keybindings = true;
                        fuzzyCompletion = true;
                };
        };
        home-manager.users.will = {
                /* The home.stateVersion option does not have a default and must be set */
                home.stateVersion = "23.05";
                /* Here goes the rest of your home-manager config, e.g. home.packages = [ pkgs.foo ]; */
                programs = {
                        git = {
                                enable = true;
                                userName  = "Will Hansen";
                                userEmail = "[email protected]";
                        };
                        helix = {
                                enable = true;
                                languages = {
                                        language = [{
                                                name = "rust";
                                                auto-format = false;
                                        }];
                                };
                                settings = {
                                        theme = "molokai"; # TODO: this theme doesn't work because colors seem to be limited
                                        editor = {
                                                lsp = {
                                                        display-messages = true; # not totally sure this is necessary...
                                                };
                                                cursor-shape.insert = "bar";
                                                indent-guides.render = true;
                                                soft-wrap.enable = true;
                                        };
                                };
                        };
                        tmux = {
                                enable = true;

                                # Stop tmux+escape craziness.
                                escapeTime = 0;

                                mouse = true;
                                keyMode = "vi";

                                # New session if trying to attach and none are running
                                newSession = true; 

                                plugins = with pkgs; [
                                        # TODO: does not seem to work
                                        #tmuxPlugins.better-mouse-mode
                                        #tmuxPlugins.yank
                                ];

                                extraConfig = ''
                                        #set -g @emulate-scroll-for-no-mouse-alternate-buffer "on"
                                        '';
                        };
                        neovim = {
                                enable = true;
                                defaultEditor = true;
                                vimAlias = true;
                                viAlias = true;
                                extraConfig = ''
                                        set number
                                        '';
                        };
                };
        };

}

Priorities

Add 👍 to issues you find important.

[fricklerhandwerk]

Hey @willhansen, thanks a lot for the elaborate feedback.

I fully appreciate your concern, and unfortunately things are as they are with official documentation: the documentation team simply didn't get to NixOS yet, and we have no one maintaining NixOS-specific documentation. Sorry that this reply amounts to "you're on your own for now". It's been that way for the past years in most areas of the Nix ecosystem, but at least these days we can say "we're working on it" - please have (lots of) patience and consider helping out.

We currently focus on the reference manuals for Nix and Nixpkgs, and first steps with Nix using stable interfaces, mainly because after extensive consideration we concluded that getting the basics right will scale better in the long run. From that particular perspective, arguably NixOS can be considered an advanced use case, even if that's what most new users come for.

As I understand it, flakes are "the way to go".

I'm curious how specifically you came to that conclusion. Third party documentation is full of such statements, but which resource convinced you of this?

The @NixOS/documentation-team just recently merged a piece with our current consensus on flakes: https://nix.dev/recipes/faq#should-i-enable-flakes

[willhansen]

I was convinced to use flakes by a combination of wanting my configuration to be 100% declarative, which meant avoiding the nix-channel --add commands, and this text box:

https://zero-to-nix.com/concepts/flakes

[fricklerhandwerk]

Thank you for sharing.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-07-31-documentation-team-meeting-notes-68/31127/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-03-documentation-team-meeting-notes-69/31263/1

[fricklerhandwerk]

Closing this since we had https://nix.dev/tutorials/nixos/nixos-configuration-on-vm for a while. More is envisioned: #738 #572