Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/migalmoreno/ordenada

A reproducible development environment for Nix
https://github.com/migalmoreno/ordenada

nix nixos nixos-configuration

Last synced: about 2 months ago
JSON representation

A reproducible development environment for Nix

Awesome Lists containing this project

README 

        
# -*- mode: org; org-html-head-include-default-style: nil; org-html-postamble: nil; org-export-with-author: nil; org-export-with-date: nil; -*-

#+OPTIONS: toc:nil num:nil

#+title: ordenada

Ordenada is a Reproducible Development Environment for Nix. It's based on the [[https://nixos.org/][Nix]] package manager and it draws inspiration from the [[https://git.sr.ht/~abcdw/rde][RDE]] configuration framework for [[https://guix.gnu.org/][GNU Guix]]. Its main goal is to serve as a layer of abstraction on top of the standard Nix configuration tools to easily build reproducible multi-user development environments.



#+begin_quote

NOTE: Ordenada is in current development and its API is subject to change

#+end_quote



* Installation

You can install Ordenada into your NixOS configuration using [[https://nix.dev/concepts/flakes.html][Flakes]]. First, add its flake URL to your list of inputs.



#+begin_src nix

{

  inputs = {

    # < your other inputs >

    ordenada.url = "github:migalmoreno/ordenada";

  };

}

#+end_src



Import its list of modules into your configuration.



#+begin_src nix

{

  outputs =

    { nixpkgs, ordenada, ... }:

    {

      nixosConfigurations."" = nixpkgs.lib.nixosSystem {

        system = "x86_64-linux";

        modules = [

          # < your other modules >

          ordenada.nixosModules.ordenada

        ];

      };

    };

}

#+end_src



Optionally, if you want to make use of Ordenada's utility library, to e.g. create your own features, add the following to your configuration.



#+begin_src nix

nixpkgs.overlays = [ ordenada.overlays.default ];

#+end_src



* Usage

Ordenada's configuration is centered around users and features. Features are blocks of configuration that provide certain functionality, such as setting up your GnuPG keys, or configuring your window manager. These have many available options you can configure to fit your needs.



In a typical single user setup, you just need to add a "global" attrset of features and add your user to the users attrset in the Ordenada configuration.



#+begin_src nix

{ config, pkgs, ... }:



{

  ordenada = {

    users = {

      user1 = { };

    };

    features = {

      userInfo = {

        username = "user1";

      };

      home.enable = true;

      gtk = {

        enable = true;

        theme = {

          name = "adw-gtk3";

          package = pkgs.adw-gtk3;

        };

      };

      emacs = {

        enable = true;

        all-the-icons.enable = true;

        eglot.enable = true;

        modus-themes = {

          enable = true;

          dark = true;

        };

      };

      sway.enable = true;

      waybar = {

        enable = true;

        modules = with config.ordenada.features.waybar.defaultModules; [

          swayWorkspaces

          swayWindow

          pulseaudio

          battery

          clock

        ];

      };

    };

  };

}

#+end_src



In more complex multi-user installations, you can modify the attrset of user features to match each user's needs. As shown in the example below, you could make user =john= augment the global list of features with ones specific to him. Alternatively, you could also create an attrset of user features from scratch and augment certain features as you go, like in the case of the =alice= user below.



#+begin_src nix

{ config, ... }:



{

  ordenada = {

    users = {

      john = {

        features = config.ordenada.features // {

          emacs.spelling.enable = true;

          firefox.enable = false;

        };

      };

      alice = {

        features = with config.ordenada.features; {

          userInfo = {

            username = "alice";

          };

          inherit gnupg;

          home.enable = true;

          bash.enable = true;

          emacs = with emacs; {

            enable = true;

            inherit smartparens org-roam vertico;

          };

        };

      };

    };

    features = {

      userInfo = {

        username = "john";

      };

      # < attrset of rest of global features >

    };

  };

}

#+end_src



With the above setup, two users =john= and =alice= will be configured in the system. Note that users inherit all "global" features by default. =john= will end up with an augmented global features setup while =alice= will only have the features =home=, =bash=, the inherited global =gnupg= feature, =emacs=, and the inherited global attrset of =emacs= features (=emacs.smartparens=, =emacs.org-roam=, and =emacs.vertico=)  .



By default, settings for each configured global feature will be inherited by each user feature, so beware that if you write a user features attrset from scratch (e.g. =alice='s example above) you won't have to include all the global configuration again for a new user feature (like the  =home=, =bash=, and =emacs= features above). However, if you need the default values of the new user feature, i.e. those that are not explicitly set in the global feature, you'll need to explicitly inherit from the global feature, such as the case with the =gnupg= feature above.



* Extending it

You can use Ordenada's utilities to extend its available features with your own. For instance, the following shows how to create a feature =example=.



#+begin_src nix

{

  config,

  lib,

  pkgs,

  ...

}:



with pkgs.lib.ordenada;



let

  cfg = config.ordenada.features.example;

in

{

  options = {

    ordenada.features.example = {

      enable = lib.mkEnableOption "the example feature";

      message = lib.mkOption {

        type = lib.types.str;

        description = "The message to show.";

        default = "";

      };

    };

  };

  config = (

    lib.mkMerge [

      (lib.mkIf cfg.enable {

        environment.sessionVariables = {

          EXAMPLE_ENV = 1;

        };

      })

      {

        home-manager = mkHomeConfig config "example" (user: {

          home.sessionVariables = lib.mkIf (hasFeature "acme" user) {

            EXAMPLE_HOME_ENV = "EXAMPLE_HOME_ENV_VALUE";

          };

          programs.emacs = mkElispConfig {

            name = "ordenada-example";

            config = ''

              ;; < your Elisp configuration >

              (setq my-elisp-value ${user.features.example.message})

            '';

            elispPackages = [ ];

            summary = "My example Emacs feature";

          };

        });

      }

    ]

  );

}

#+end_src



The =example= feature above showcases many common workflows inside features. First, we define a list of options specific to this feature which we'll be able to access from anywhere in our configuration. Then, we add a "system" configuration which is conditional on the feature being enabled. Next, we have a "home" configuration that we call with the special utility =mkHomeConfig=, which allows us to configure home settings for all our Ordenada users. In this example, we're setting a home environment variable which will be set as long as the =acme= feature is enabled, which we check via the =hasFeature= utility. Then, we set an Emacs Lisp configuration via the =mkElispConfig= utility which will add a new Emacs configuration package specific to this feature. Note how we can interpolate values in our Emacs configuration with our user features.



* Configuration Options

See [[https://migalmoreno.com/projects/ordenada.html#configuration-options][the project's homepage]] for the full list of configuration options.