Nixos

NixOS Development

Overview

Build and maintain NixOS configurations using Nix flakes. Focus on multi-repo composition, airgapped deployments, and declarative infrastructure.

Quick Reference

Flake Structure

Standard multi-repo flake pattern:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    # Pin dependent flakes to same nixpkgs
    other-flake.url = "git+ssh://gitlab.example.com/repo";
    other-flake.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, nixpkgs, other-flake, ... }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
    in {
      # NixOS system configurations
      nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          other-flake.nixosModules.default
          ./configuration.nix
        ];
      };

      # Reusable NixOS modules
      nixosModules.default = import ./modules;

      # Packages
      packages.${system} = { /* ... */ };

      # Development shells
      devShells.${system}.default = pkgs.mkShell { /* ... */ };
    };
}

NixOS Module Pattern

Export modules for composition:

# modules/default.nix
{ config, lib, pkgs, ... }:
{
  imports = [ ./service.nix ];

  options.myModule.enable = lib.mkEnableOption "my module";

  config = lib.mkIf config.myModule.enable {
    # configuration here
  };
}

OCI Image Packaging

For airgapped deployments, package images as store paths:

# Single image to OCI tarball
imagePackage = pkgs.runCommand "image-name" {
  buildInputs = [ pkgs.skopeo ];
} ''
  skopeo copy docker://registry/image:tag oci-archive:$out
'';

Helm + Kustomize in Nix

Render manifests at build time:

manifests = pkgs.runCommand "manifests" {
  buildInputs = [ pkgs.kubernetes-helm pkgs.kustomize ];
} ''
  helm template release ${./chart} --namespace ns > base.yaml
  kustomize build ${./overlays} > $out
'';

Detailed References

For comprehensive documentation on specific topics:

Common Patterns

Pin nixpkgs across repos

Use inputs.X.inputs.nixpkgs.follows = "nixpkgs" to ensure consistent package versions.

Conditional module loading

imports = lib.optionals config.feature.enable [ ./optional-module.nix ];

Lazy evaluation with mkIf

Always use lib.mkIf for conditional config to avoid infinite recursion:

config = lib.mkIf config.myService.enable { /* ... */ };

Override priorities

• lib.mkDefault (priority 1000) - easily overridable defaults
• lib.mkForce (priority 50) - force value regardless of other definitions
• lib.mkOverride N - custom priority (lower = higher priority)

Troubleshooting

"error: getting status of '/nix/store/...': No such file or directory"

Missing store path. Run nix build or ensure binary cache is configured.

"error: infinite recursion encountered"

Using config values in imports or not wrapping conditional config in lib.mkIf.

"error: attribute 'X' missing"

Check flake inputs match expected names. Verify follows directives.

Flake not seeing local changes

Run git add . - flakes ignore untracked files.