mirror of
https://github.com/divnix/digga.git
synced 2024-12-23 08:02:21 +03:00
1067 lines
64 KiB
HTML
1067 lines
64 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>devos docs</title>
|
||
<meta name="robots" content="noindex" />
|
||
<!-- Custom HTML head -->
|
||
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff" />
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script type="text/javascript">
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script type="text/javascript">
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script type="text/javascript">
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script type="text/javascript">
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="../index.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="start/index.html"><strong aria-hidden="true">2.</strong> Quick Start</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="start/iso.html"><strong aria-hidden="true">2.1.</strong> ISO</a></li><li class="chapter-item expanded "><a href="start/bootstrapping.html"><strong aria-hidden="true">2.2.</strong> Bootstrapping</a></li><li class="chapter-item expanded "><a href="start/from-nixos.html"><strong aria-hidden="true">2.3.</strong> From NixOS</a></li></ol></li><li class="chapter-item expanded "><a href="concepts/index.html"><strong aria-hidden="true">3.</strong> Key Concepts</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="concepts/hosts.html"><strong aria-hidden="true">3.1.</strong> Hosts</a></li><li class="chapter-item expanded "><a href="concepts/overrides.html"><strong aria-hidden="true">3.2.</strong> Overrides</a></li><li class="chapter-item expanded "><a href="concepts/profiles.html"><strong aria-hidden="true">3.3.</strong> Profiles</a></li><li class="chapter-item expanded "><a href="concepts/suites.html"><strong aria-hidden="true">3.4.</strong> Suites</a></li><li class="chapter-item expanded "><a href="concepts/users.html"><strong aria-hidden="true">3.5.</strong> Users</a></li></ol></li><li class="chapter-item expanded "><a href="outputs/index.html"><strong aria-hidden="true">4.</strong> Outputs</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="outputs/modules.html"><strong aria-hidden="true">4.1.</strong> Modules</a></li><li class="chapter-item expanded "><a href="outputs/overlays.html"><strong aria-hidden="true">4.2.</strong> Overlays</a></li><li class="chapter-item expanded "><a href="outputs/pkgs.html"><strong aria-hidden="true">4.3.</strong> Packages</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">5.</strong> Concerns</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="secrets.html"><strong aria-hidden="true">5.1.</strong> Secrets</a></li><li class="chapter-item expanded "><a href="tests.html"><strong aria-hidden="true">5.2.</strong> Tests</a></li></ol></li><li class="chapter-item expanded "><a href="bud/index.html"><strong aria-hidden="true">6.</strong> Helper Script – bud</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="bud/get.html"><strong aria-hidden="true">6.1.</strong> get</a></li></ol></li><li class="chapter-item expanded "><a href="integrations/index.html"><strong aria-hidden="true">7.</strong> Integrations</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="integrations/cachix.html"><strong aria-hidden="true">7.1.</strong> Cachix</a></li><li class="chapter-item expanded "><a href="integrations/deploy.html"><strong aria-hidden="true">7.2.</strong> Deploy RS</a></li><li class="chapter-item expanded "><a href="integrations/nvfetcher.html"><strong aria-hidden="true">7.3.</strong> NvFetcher</a></li><li class="chapter-item expanded "><a href="integrations/hercules.html"><strong aria-hidden="true">7.4.</strong> Hercules CI</a></li></ol></li><li class="chapter-item expanded "><a href="CONTRIBUTING.html"><strong aria-hidden="true">8.</strong> Contributing</a></li></ol>
|
||
</div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky bordered">
|
||
<div class="left-buttons">
|
||
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</button>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">devos docs</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script type="text/javascript">
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<p><a href="https://nixos.org"><img src="https://img.shields.io/badge/NixOS-unstable-blue.svg?style=flat&logo=NixOS&logoColor=white" alt="NixOS" /></a>
|
||
<a href="https://mit-license.org"><img src="https://img.shields.io/github/license/divnix/devos" alt="MIT License" /></a>
|
||
<a href="https://matrix.to/#/#devos:nixos.org"><img src="https://img.shields.io/matrix/devos:nixos.org.svg?label=%23devos%3Anixos.org&logo=matrix&server_fqdn=matrix.org" alt="Chat" /></a></p>
|
||
<blockquote>
|
||
<h4 id="-advisory-"><a class="header" href="#-advisory-">⚠ Advisory ⚠</a></h4>
|
||
<p>DevOS requires the <a href="https://nixos.wiki/wiki/Flakes">flakes</a> feature available via an <em>experimental</em>
|
||
branch of <a href="https://nixos.org/manual/nix/stable">nix</a>. Until nix 2.4 is released, this project
|
||
should be considered unstable.</p>
|
||
</blockquote>
|
||
<h3 id="why"><a class="header" href="#why">Why?</a></h3>
|
||
<p>Make an awesome template for NixOS users, with consideration for common tools like <a href="https://nix-community.github.io/home-manager">home-manager</a>,
|
||
<a href="https://github.com/numtide/devshell">devshell</a>, and <a href=".././doc/integrations">more</a>.</p>
|
||
<h3 id="no-why-flakes"><a class="header" href="#no-why-flakes">No. Why <em>flakes</em>?</a></h3>
|
||
<p>Flakes are a part of an explicit push to improve <a href="https://github.com/NixOS/nix/blob/master/doc/manual/src/contributing/cli-guideline.md">Nix's UX</a>, and have become an integral part of that effort. </p>
|
||
<p>They also make <a href="https://nixos.org/manual/nix/unstable/expressions/expression-syntax.html">Nix expressions</a> easier to distribute and reuse with convient <a href="https://github.com/NixOS/nix/blob/master/src/nix/flake.md#flake-references">flake references</a> for building or using packages, modules, and whole systems.</p>
|
||
<h2 id="getting-started"><a class="header" href="#getting-started">Getting Started</a></h2>
|
||
<p>Check out the <a href="https://devos.divnix.com/start">guide</a> to get up and running.
|
||
Also, have a look at <a href=".././flake.nix"><em>flake.nix</em></a>. If anything is not immediately
|
||
discoverable via "<a href="https://github.com/divnix/digga"><code>digga</code></a>'s <a href="https://github.com/divnix/digga/tree/main/src/mkFlake"><code>mkFlake</code></a>,
|
||
please file a bug report.</p>
|
||
<h3 id="status-beta"><a class="header" href="#status-beta">Status: Beta</a></h3>
|
||
<p>Although this project has already matured quite a bit, especially through
|
||
recent outfactoring of <a href="https://github.com/divnix/digga"><code>digga</code></a>, a fair amount of api polishing is still
|
||
expected. There are unstable versions (0.<em>x</em>.<em>x</em>) to help users keep track
|
||
of changes and progress, and a <a href="https://github.com/divnix/devos/tree/develop"><code>develop</code></a> branch for the brave 😜</p>
|
||
<h2 id="in-the-wild"><a class="header" href="#in-the-wild">In the Wild</a></h2>
|
||
<ul>
|
||
<li>The original <a href="https://github.com/nrdxp/devos/tree/nrd">authors</a></li>
|
||
</ul>
|
||
<h2 id="shoulders"><a class="header" href="#shoulders">Shoulders</a></h2>
|
||
<p>This work does not reinvent the wheel. It stands on the <a href="https://en.wikipedia.org/wiki/Standing_on_the_shoulders_of_giants">shoulders of the
|
||
following giants</a>:</p>
|
||
<h3 id="onion--like-the-layers-of-an-onion"><a class="header" href="#onion--like-the-layers-of-an-onion">:onion: — like the layers of an onion</a></h3>
|
||
<ul>
|
||
<li><a href="https://github.com/divnix/digga"><code>divnix/digga</code></a></li>
|
||
<li><a href="https://github.com/gytis-ivaskevicius/flake-utils-plus"><code>gytis-ivaskevicius/flake-utils-plus</code></a></li>
|
||
<li><a href="https://github.com/numtide/flake-utils"><code>numtide/flake-utils</code></a></li>
|
||
</ul>
|
||
<h3 id="family--like-family"><a class="header" href="#family--like-family">:family: — like family</a></h3>
|
||
<ul>
|
||
<li><a href="https://github.com/numtide/devshell"><code>numtide/devshell</code></a></li>
|
||
<li><a href="https://github.com/serokell/deploy-rs"><code>serokell/deploy-rs</code></a></li>
|
||
<li><a href="https://github.com/berberman/nvfetcher"><code>berberman/nvfetcher</code></a></li>
|
||
<li><a href="https://github.com/NixOS/nixpkgs"><code>NixOS/nixpkgs</code></a></li>
|
||
</ul>
|
||
<p>:heart:</p>
|
||
<h2 id="inspiration--art"><a class="header" href="#inspiration--art">Inspiration & Art</a></h2>
|
||
<ul>
|
||
<li><a href="https://github.com/hlissner/dotfiles">hlissner/dotfiles</a></li>
|
||
<li><a href="https://github.com/nix-community/nix-user-chroot">nix-user-chroot</a></li>
|
||
<li><a href="https://github.com/tweag/nickel">Nickel</a></li>
|
||
<li><a href="https://github.com/nix-community/awesome-nix">Awesome Nix</a></li>
|
||
<li><a href="https://github.com/numtide/devshell">devshell</a></li>
|
||
</ul>
|
||
<h2 id="divnix"><a class="header" href="#divnix">Divnix</a></h2>
|
||
<p>The divnix org is an open space that spontaniously formed out of "the Nix".
|
||
It is really just a place where otherwise unrelated people a) get
|
||
together and b) stuff done.</p>
|
||
<p>It's a place to stop "geeking out in isolation" (or within company boundaries),
|
||
experiment and learn together and iterate quickly on best practices. That's what it is.</p>
|
||
<p>It might eventually become a non-profit if that's not too complicated or if those
|
||
goals are sufficiently upstreamed into "the Nix", dissolved.</p>
|
||
<h1 id="license"><a class="header" href="#license">License</a></h1>
|
||
<p>DevOS is licensed under the <a href="https://mit-license.org">MIT License</a>.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="quick-start"><a class="header" href="#quick-start">Quick Start</a></h1>
|
||
<p>The only dependency is nix, so make sure you have it <a href="https://nixos.org/manual/nix/stable/#sect-multi-user-installation">installed</a>.</p>
|
||
<h2 id="get-the-template"><a class="header" href="#get-the-template">Get the Template</a></h2>
|
||
<p>Here is a snippet that will get you the template without the git history:</p>
|
||
<pre><code class="language-sh">nix-shell -p cachix --run "cachix use nrdxp"
|
||
|
||
nix-shell https://github.com/divnix/devos/archive/main.tar.gz -A shell \
|
||
--run "bud get main"
|
||
|
||
cd devos
|
||
|
||
nix-shell
|
||
|
||
git init
|
||
git add .
|
||
git commit -m init
|
||
</code></pre>
|
||
<p>This will place you in a new folder named <code>devos</code> with git initialized, and a
|
||
nix-shell that provides all the dependencies, including the unstable nix
|
||
version required.</p>
|
||
<p>In addition, the <a href="start/../integrations/cachix.html">binary cache</a> is added for faster deployment.</p>
|
||
<blockquote>
|
||
<h5 id="notes"><a class="header" href="#notes"><em>Notes:</em></a></h5>
|
||
<ul>
|
||
<li>Flakes ignore files that have not been added to git, so be sure to stage new
|
||
files before building the system.</li>
|
||
<li>You can choose to simply clone the repo with git if you want to follow
|
||
upstream changes.</li>
|
||
<li>If the <code>nix-shell -p cachix --run "cachix use nrdxp"</code> line doesn't work
|
||
you can try with sudo: <code>sudo nix-shell -p cachix --run "cachix use nrdxp"</code></li>
|
||
</ul>
|
||
</blockquote>
|
||
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps:</a></h2>
|
||
<ul>
|
||
<li><a href="start/./iso.html">Make installable ISO</a></li>
|
||
<li><a href="start/./bootstrapping.html">Bootstrap Host</a></li>
|
||
<li><a href="start/./from-nixos.html">Already on NixOS</a></li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="iso"><a class="header" href="#iso">ISO</a></h1>
|
||
<p>Making and writing an installable iso for <code>hosts/bootstrap.nix</code> is as simple as:</p>
|
||
<pre><code class="language-sh">bud build bootstrap bootstrapIso
|
||
sudo -E $(which bud) burn
|
||
</code></pre>
|
||
<p>This works for any host.</p>
|
||
<h2 id="iso-image-nix-store--cache"><a class="header" href="#iso-image-nix-store--cache">ISO image nix store & cache</a></h2>
|
||
<p>The iso image holds the store to the live environment and <em>also</em> acts as a binary cache
|
||
to the installer. To considerably speed up things, the image already includes all flake
|
||
<code>inputs</code> as well as the <code>devshell</code> closures.</p>
|
||
<p>While you <em>could</em> provision any machine with a single stick, a custom-made iso for
|
||
the host you want to install DevOS to, maximises those local cache hits.</p>
|
||
<p>For hosts that don't differ too much, a single usb stick might be ok, whereas when
|
||
there are bigger differences, a custom-made usb stick will be considerably faster.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="bootstrapping"><a class="header" href="#bootstrapping">Bootstrapping</a></h1>
|
||
<p>This will help you boostrap a bare host with the help of the
|
||
<a href="start/./iso.html">bespoke iso</a> live installer.</p>
|
||
<p><em>Note: nothing prevents you from remotely executing the boostrapping
|
||
process. See below.</em></p>
|
||
<p>Once your target host has booted into the live iso, you need to partition
|
||
and format your disk according to the <a href="https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning">official manual</a>.</p>
|
||
<h2 id="mount-partitions"><a class="header" href="#mount-partitions">Mount partitions</a></h2>
|
||
<p>Then properly mount the formatted partitions at <code>/mnt</code>, so that you can
|
||
install your system to those new partitions.</p>
|
||
<p>Mount <code>nixos</code> partition to <code>/mnt</code> and — for UEFI — <code>boot</code>
|
||
partition to <code>/mnt/boot</code>:</p>
|
||
<pre><code class="language-console">$ mount /dev/disk/by-label/nixos /mnt
|
||
$ mkdir -p /mnt/boot && mount /dev/disk/by-label/boot /mnt/boot # UEFI only
|
||
$ swapon /dev/disk/by-label/swap
|
||
</code></pre>
|
||
<p>Add some extra space to the store. In the iso, it's running on a tmpfs
|
||
off your RAM:</p>
|
||
<pre><code class="language-console">$ mkdir -p /mnt/tmpstore/{work,store}
|
||
$ mount -t overlay overlay -olowerdir=/nix/store,upperdir=/mnt/tmpstore/store,workdir=/mnt/tmpstore/work /nix/store
|
||
</code></pre>
|
||
<h2 id="install"><a class="header" href="#install">Install</a></h2>
|
||
<p>Install off of a copy of devos from the time the iso was built:</p>
|
||
<pre><code class="language-console">$ cd /iso/devos
|
||
$ nixos-install --flake .#NixOS
|
||
</code></pre>
|
||
<h2 id="notes-of-interest"><a class="header" href="#notes-of-interest">Notes of interest</a></h2>
|
||
<h3 id="remote-access-to-the-live-installer"><a class="header" href="#remote-access-to-the-live-installer">Remote access to the live installer</a></h3>
|
||
<p>The iso live installer comes preconfigured with a network configuration
|
||
which announces it's hostname via <a href="https://en.wikipedia.org/wiki/Multicast_DNS">MulticastDNS</a> as <code>hostname.local</code>,
|
||
that is <code>bootstrap.local</code> in the <a href="start/./iso">iso example</a>.</p>
|
||
<p>In the rare case that <a href="https://en.wikipedia.org/wiki/Multicast_DNS">MulticastDNS</a> is not availabe or turned off
|
||
in your network, there is a static link-local IPv6 address configured to
|
||
<code>fe80::47</code>(mnemonic from the letter's position in the english alphabet:
|
||
<code>n=14 i=9 x=24; 47 = n+i+x</code>).</p>
|
||
<p>Provided that you have added your public key to the authorized keys of the
|
||
<code>root</code> user <em>(hint: <a href="start/../integrations/deploy.html"><code>deploy-rs</code></a> needs passwordless
|
||
sudo access)</em>:</p>
|
||
<pre><code class="language-nix">{ ... }:
|
||
{
|
||
users.users.root.openssh.authorizedKeys.keyFiles = [
|
||
../secrets/path/to/key.pub
|
||
];
|
||
}
|
||
</code></pre>
|
||
<p>You can then ssh into the live installer through one of the
|
||
following options:</p>
|
||
<pre><code class="language-console">ssh root@bootstrap.local
|
||
|
||
ssh root@fe80::47%eno1 # where eno1 is your network interface on which you are linked to the target
|
||
</code></pre>
|
||
<p><em>Note: the <a href="https://tools.ietf.org/html/rfc7404">static link-local IPv6 address</a> and <a href="https://en.wikipedia.org/wiki/Multicast_DNS">MulticastDNS</a> is only
|
||
configured on the live installer. If you wish to enable <a href="https://en.wikipedia.org/wiki/Multicast_DNS">MulticastDNS</a>
|
||
for your environment, you ought to configure that in a regular <a href="start/../concepts/profiles.html">profile</a>.</em></p>
|
||
<h3 id="eui-64-lla--host-identity"><a class="header" href="#eui-64-lla--host-identity">EUI-64 LLA & Host Identity</a></h3>
|
||
<p>The iso's IPv6 Link Local Address (LLA) is configured with a static 64-bit Extended
|
||
Unique Identifiers (EUI-64) that is derived from the host interface's Message
|
||
Authentication Code (MAC) address.</p>
|
||
<p>After a little while (a few seconds), you can remotely discover this unique and host
|
||
specific address over <a href="https://en.wikipedia.org/wiki/Neighbor_Discovery_Protocol">NDP</a> for example with:</p>
|
||
<pre><code class="language-console">ip -6 neigh show # also shows fe80::47
|
||
</code></pre>
|
||
<p><em><strong>This LLA is stable for the host, unless you need to swap that particular network card.</strong></em>
|
||
Under this reservation, though, you may use this EUI-64 to wire up a specific
|
||
(cryptographic) host identity.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="from-nixos"><a class="header" href="#from-nixos">From NixOS</a></h1>
|
||
<h2 id="generate-configuration"><a class="header" href="#generate-configuration">Generate Configuration</a></h2>
|
||
<p>Assuming you're happy with your existing partition layout, you can generate a
|
||
basic NixOS configuration for your system using:</p>
|
||
<pre><code class="language-sh">bud up
|
||
</code></pre>
|
||
<p>This will make a new file <code>hosts/up-$(hostname).nix</code>, which you can edit to
|
||
your liking.</p>
|
||
<p>You must then add a host to <code>nixos.hosts</code> in flake.nix:</p>
|
||
<pre><code class="language-nix">{
|
||
nixos.hosts = {
|
||
modules = hosts/NixOS.nix;
|
||
};
|
||
}
|
||
</code></pre>
|
||
<p>Make sure your <code>i18n.defaultLocale</code> and <code>time.timeZone</code> are set properly for
|
||
your region. Keep in mind that <code>networking.hostName</code> will be automatically
|
||
set to the name of your host;</p>
|
||
<p>Now might be a good time to read the docs on <a href="start/../concepts/suites.html">suites</a> and
|
||
<a href="start/../concepts/profiles.html">profiles</a> and add or create any that you need.</p>
|
||
<blockquote>
|
||
<h5 id="note"><a class="header" href="#note"><em>Note:</em></a></h5>
|
||
<p>While the <code>up</code> sub-command is provided as a convenience to quickly set up and
|
||
install a "fresh" NixOS system on current hardware, committing these files is
|
||
discouraged.</p>
|
||
<p>They are placed in the git staging area automatically because they would be
|
||
invisible to the flake otherwise, but it is best to move what you need from
|
||
them directly into a host module of your own making, and commit that instead.</p>
|
||
</blockquote>
|
||
<h1 id="installation"><a class="header" href="#installation">Installation</a></h1>
|
||
<p>Once you're ready to deploy <code>hosts/my-host.nix</code>:</p>
|
||
<pre><code class="language-sh">bud my-host switch
|
||
</code></pre>
|
||
<p>This calls <code>nixos-rebuild</code> with sudo to build and install your configuration.</p>
|
||
<blockquote>
|
||
<h5 id="notes-1"><a class="header" href="#notes-1"><em>Notes:</em></a></h5>
|
||
<ul>
|
||
<li>Instead of <code>switch</code>, you can pass <code>build</code>, <code>test</code>, <code>boot</code>, etc just as with
|
||
<code>nixos-rebuild</code>.</li>
|
||
</ul>
|
||
</blockquote>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="key-concepts"><a class="header" href="#key-concepts">Key Concepts</a></h1>
|
||
<p>Key concepts are derived from <a href="https://github.com/divnix/digga">digga</a>. Please refer to its
|
||
<a href="https://digga.divnix.com">docs</a> for more details.</p>
|
||
<p>This section is dedicated to helping you develop a more hands on
|
||
understanding of them them.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="hosts"><a class="header" href="#hosts">Hosts</a></h1>
|
||
<p>Nix flakes contain an output called <code>nixosConfigurations</code> declaring an
|
||
attribute set of valid NixOS systems. To simplify the management and creation
|
||
of these hosts, devos automatically imports every <em>.nix</em> file inside this
|
||
directory to the mentioned attribute set, applying the projects defaults to
|
||
each. The only hard requirement is that the file contain a valid NixOS module.</p>
|
||
<p>As an example, a file <code>hosts/system.nix</code> or <code>hosts/system/default.nix</code> will
|
||
be available via the flake output <code>nixosConfigurations.system</code>. You can have
|
||
as many hosts as you want and all of them will be automatically imported based
|
||
on their name.</p>
|
||
<p>For each host, the configuration automatically sets the <code>networking.hostName</code>
|
||
attribute to the folder name or name of the file minus the <em>.nix</em> extension. This
|
||
is for convenience, since <code>nixos-rebuild</code> automatically searches for a configuration
|
||
matching the current systems hostname if one is not specified explicitly.</p>
|
||
<p>You can set channels, systems, and add extra modules to each host by editing the
|
||
<code>nixos.hosts</code> argument in flake.nix. This is the perfect place to import
|
||
host specific modules from external sources, such as the
|
||
<a href="https://github.com/NixOS/nixos-hardware">nixos-hardware</a> repository.</p>
|
||
<p>It is recommended that the host modules only contain configuration information
|
||
specific to a particular piece of hardware. Anything reusable across machines
|
||
is best saved for <a href="concepts/./profiles.html">profile modules</a>.</p>
|
||
<p>This is a good place to import sets of profiles, called <a href="concepts/./suites.html">suites</a>,
|
||
that you intend to use on your machine.</p>
|
||
<h2 id="example"><a class="header" href="#example">Example</a></h2>
|
||
<p>flake.nix:</p>
|
||
<pre><code class="language-nix">{
|
||
nixos = {
|
||
imports = [ (devos.lib.importHosts ./hosts) ];
|
||
hosts = {
|
||
librem = {
|
||
channelName = "latest";
|
||
modules = [ nixos-hardware.nixosModules.purism-librem-13v3 ];
|
||
};
|
||
};
|
||
};
|
||
}
|
||
</code></pre>
|
||
<p>hosts/librem.nix:</p>
|
||
<pre><code class="language-nix">{ suites, ... }:
|
||
{
|
||
imports = suites.laptop;
|
||
|
||
boot.loader.systemd-boot.enable = true;
|
||
boot.loader.efi.canTouchEfiVariables = true;
|
||
|
||
fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
|
||
}
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="overrides"><a class="header" href="#overrides">Overrides</a></h1>
|
||
<p>Each NixOS host follows one channel. But many times it is useful to get packages
|
||
or modules from different channels.</p>
|
||
<h2 id="packages"><a class="header" href="#packages">Packages</a></h2>
|
||
<p>You can make use of <code>overlays/overrides.nix</code> to override specific packages in the
|
||
default channel to be pulled from other channels. That file is simply an example
|
||
of how any overlay can get <code>channels</code> as their first argument.</p>
|
||
<p>You can add overlays to any channel to override packages from other channels.</p>
|
||
<p>Pulling the manix package from the <code>latest</code> channel:</p>
|
||
<pre><code class="language-nix">channels: final: prev: {
|
||
__dontExport = true;
|
||
inherit (pkgs.latest) manix;
|
||
}
|
||
</code></pre>
|
||
<p>It is recommended to set the <code>__dontExport</code> property for override specific
|
||
overlays. <code>overlays/overrides.nix</code> is the best place to consolidate all package
|
||
overrides and the property is already set for you.</p>
|
||
<h2 id="modules"><a class="header" href="#modules">Modules</a></h2>
|
||
<p>You can also pull modules from other channels. All modules have access to the
|
||
<code>modulesPath</code> for each channel as <code><channelName>ModulesPath</code>. And you can use
|
||
<code>disabledModules</code> to remove modules from the current channel.</p>
|
||
<p>To pull zsh module from the <code>latest</code> channel this code can be placed in any module, whether its your host file, a profile, or a module in ./modules etc:</p>
|
||
<pre><code class="language-nix">{ latestModulesPath }:
|
||
{
|
||
imports = [ "${latestModulesPath}/programs/zsh/zsh.nix" ];
|
||
disabledModules = [ "programs/zsh/zsh.nix" ];
|
||
}
|
||
</code></pre>
|
||
<blockquote>
|
||
<h5 id="note-1"><a class="header" href="#note-1"><em>Note:</em></a></h5>
|
||
<p>Sometimes a modules name will change from one branch to another.</p>
|
||
</blockquote>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="profiles"><a class="header" href="#profiles">Profiles</a></h1>
|
||
<p>Profiles are a convenient shorthand for the <a href="https://nixos.org/manual/nixos/stable/index.html#sec-option-definitions"><em>definition</em></a> of
|
||
<a href="https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules">options</a> in contrast to their <a href="https://nixos.org/manual/nixos/stable/index.html#sec-option-declarations"><em>declaration</em></a>. They're
|
||
built into the NixOS module system for a reason: to elegantly provide a clear
|
||
separation of concerns.</p>
|
||
<h2 id="creation"><a class="header" href="#creation">Creation</a></h2>
|
||
<p>Profiles are created with the <code>rakeLeaves</code> function which recursively collects
|
||
<code>.nix</code> files from within a folder. The recursion stops at folders with a <code>default.nix</code>
|
||
in them. You end up with an attribute set with leaves(paths to profiles) or
|
||
nodes(attrsets leading to more nodes or leaves).</p>
|
||
<p>A profile is used for quick modularization of <a href="concepts/./profiles.html#subprofiles">interelated bits</a>.</p>
|
||
<blockquote>
|
||
<h5 id="notes-2"><a class="header" href="#notes-2"><em>Notes:</em></a></h5>
|
||
<ul>
|
||
<li>For <em>declaring</em> module options, there's the <a href="concepts/../outputs/modules.html">modules</a> directory.</li>
|
||
<li>This directory takes inspiration from
|
||
<a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules/profiles">upstream</a>
|
||
.</li>
|
||
</ul>
|
||
</blockquote>
|
||
<h3 id="nested-profiles"><a class="header" href="#nested-profiles">Nested profiles</a></h3>
|
||
<p>Profiles can be nested in attribute sets due to the recursive nature of <code>rakeLeaves</code>.
|
||
This can be useful to have a set of profiles created for a specific purpose. It is
|
||
sometimes useful to have a <code>common</code> profile that has high level concerns related
|
||
to all its sister profiles.</p>
|
||
<h3 id="example-1"><a class="header" href="#example-1">Example</a></h3>
|
||
<p>profiles/develop/common.nix:</p>
|
||
<pre><code class="language-nix">{
|
||
imports = [ ./zsh ];
|
||
# some generic development concerns ...
|
||
}
|
||
</code></pre>
|
||
<p>profiles/develop/zsh.nix:</p>
|
||
<pre><code class="language-nix">{ ... }:
|
||
{
|
||
programs.zsh.enable = true;
|
||
# zsh specific options ...
|
||
}
|
||
</code></pre>
|
||
<p>The examples above will end up with a profiles set like this:</p>
|
||
<pre><code class="language-nix">{
|
||
develop = {
|
||
common = ./profiles/develop/common.nix;
|
||
zsh = ./profiles/develop/zsh.nix;
|
||
};
|
||
}
|
||
</code></pre>
|
||
<h2 id="conclusion"><a class="header" href="#conclusion">Conclusion</a></h2>
|
||
<p>Profiles are the most important concept in DevOS. They allow us to keep our
|
||
Nix expressions self contained and modular. This way we can maximize reuse
|
||
across hosts while minimizing boilerplate. Remember, anything machine
|
||
specific belongs in your <a href="concepts/hosts.html">host</a> files instead.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="suites"><a class="header" href="#suites">Suites</a></h1>
|
||
<p>Suites provide a mechanism for users to easily combine and name collections of
|
||
profiles.</p>
|
||
<p><code>suites</code> are defined in the <code>importables</code> argument in either the <code>home</code> or <code>nixos</code>
|
||
namespace. They are a special case of an <code>importable</code> which is passed as a special
|
||
argument (one that can be use in an <code>imports</code> line) to your hosts. All lists defined
|
||
in <code>suites</code> are flattened and type-checked as paths.</p>
|
||
<h2 id="definition"><a class="header" href="#definition">Definition</a></h2>
|
||
<pre><code class="language-nix">rec {
|
||
workstation = [ profiles.develop profiles.graphical users.nixos ];
|
||
mobileWS = workstation ++ [ profiles.laptop ];
|
||
}
|
||
</code></pre>
|
||
<h2 id="usage"><a class="header" href="#usage">Usage</a></h2>
|
||
<p><code>hosts/my-laptop.nix</code>:</p>
|
||
<pre><code class="language-nix">{ suites, ... }:
|
||
{
|
||
imports = suites.mobileWS;
|
||
}
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><blockquote>
|
||
<h5 id="note-2"><a class="header" href="#note-2"><em>Note:</em></a></h5>
|
||
<p>This section and its semantics need a conceptiual rework.
|
||
Since recently <a href="https://digga.divnix.com/api-reference-home.html#homeusers">portable home configurations</a>
|
||
that are not bound to any specific host are a thing.</p>
|
||
</blockquote>
|
||
<h1 id="users"><a class="header" href="#users">Users</a></h1>
|
||
<p>Users are a special case of <a href="concepts/profiles.html">profiles</a> that define system
|
||
users and <a href="https://nix-community.github.io/home-manager">home-manager</a> configurations. For your convenience,
|
||
home manager is wired in by default so all you have to worry about is declaring
|
||
your users. For a fully fleshed out example, check out the developers personal
|
||
<a href="https://github.com/divnix/devos/tree/nrd/users/nrd/default.nix">branch</a>.</p>
|
||
<h2 id="basic-usage"><a class="header" href="#basic-usage">Basic Usage</a></h2>
|
||
<p><code>users/myuser/default.nix</code>:</p>
|
||
<pre><code class="language-nix">{ ... }:
|
||
{
|
||
users.users.myuser = {
|
||
isNormalUser = true;
|
||
};
|
||
|
||
home-manager.users.myuser = {
|
||
programs.mpv.enable = true;
|
||
};
|
||
}
|
||
|
||
</code></pre>
|
||
<h2 id="home-manager"><a class="header" href="#home-manager">Home Manager</a></h2>
|
||
<p>Home Manager support follows the same principles as regular nixos configurations,
|
||
it even gets its own namespace in your <code>flake.nix</code> as <code>home</code>.</p>
|
||
<p>All modules defined in <a href="https://github.com/divnix/devos/tree/main/users/modules/module-list.nix">user modules</a> will be imported to
|
||
Home Manager.
|
||
User profiles can be collected in a similar fashion as system ones into a <code>suites</code>
|
||
argument that gets passed to your home-manager users.</p>
|
||
<h3 id="example-2"><a class="header" href="#example-2">Example</a></h3>
|
||
<pre><code class="language-nix">{
|
||
home-manager.users.nixos = { suites, ... }: {
|
||
imports = suites.base;
|
||
};
|
||
}
|
||
</code></pre>
|
||
<h2 id="external-usage"><a class="header" href="#external-usage">External Usage</a></h2>
|
||
<p>You can easily use the defined home-manager configurations outside of NixOS
|
||
using the <code>homeConfigurations</code> flake output. The <a href="concepts/../bud/index.html">bud</a> helper
|
||
script makes this even easier.</p>
|
||
<p>This is great for keeping your environment consistent across Unix systems,
|
||
including OSX.</p>
|
||
<h3 id="from-within-the-projects-devshell"><a class="header" href="#from-within-the-projects-devshell">From within the projects devshell:</a></h3>
|
||
<pre><code class="language-sh"># builds the nixos user defined in the NixOS host
|
||
bud home NixOS nixos
|
||
|
||
# build and activate
|
||
bud home NixOS nixos switch
|
||
</code></pre>
|
||
<h3 id="manually-from-outside-the-project"><a class="header" href="#manually-from-outside-the-project">Manually from outside the project:</a></h3>
|
||
<pre><code class="language-sh"># build
|
||
nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPackage"
|
||
|
||
# activate
|
||
./result/activate && unlink result
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="layout"><a class="header" href="#layout">Layout</a></h1>
|
||
<p>Each of the following sections is a directory whose contents are output to the
|
||
outside world via the flake's outputs. Check each chapter for details.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="modules-1"><a class="header" href="#modules-1">Modules</a></h1>
|
||
<p>The modules directory is a replica of nixpkg's NixOS <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">modules</a>
|
||
, and follows the same semantics. This allows for trivial upstreaming into
|
||
nixpkgs proper once your module is sufficiently stable.</p>
|
||
<p>All modules linked in <em>module-list.nix</em> are automatically exported via
|
||
<code>nixosModules.<file-basename></code>, and imported into all <a href="outputs/../concepts/hosts.html">hosts</a>.</p>
|
||
<blockquote>
|
||
<h5 id="note-3"><a class="header" href="#note-3"><em>Note:</em></a></h5>
|
||
<p>This is reserved for declaring brand new module options. If you just want to
|
||
declare a coherent configuration of already existing and related NixOS options
|
||
, use <a href="outputs/../concepts/profiles.html">profiles</a> instead.</p>
|
||
</blockquote>
|
||
<h2 id="semantics"><a class="header" href="#semantics">Semantics</a></h2>
|
||
<p>In case you've never written a module for nixpkgs before, here is a brief
|
||
outline of the process.</p>
|
||
<h3 id="declaration"><a class="header" href="#declaration">Declaration</a></h3>
|
||
<p>modules/services/service-category/my-service.nix:</p>
|
||
<pre><code class="language-nix">{ config, lib, ... }:
|
||
let
|
||
cfg = config.services.myService;
|
||
in
|
||
{
|
||
options.services.myService = {
|
||
enable = lib.mkEnableOption "Description of my new service.";
|
||
|
||
# additional options ...
|
||
};
|
||
|
||
config = lib.mkIf cfg.enable {
|
||
# implementation ...
|
||
};
|
||
}
|
||
</code></pre>
|
||
<h3 id="import"><a class="header" href="#import">Import</a></h3>
|
||
<p>modules/module-list.nix:</p>
|
||
<pre><code class="language-nix">[
|
||
./services/service-category/my-service.nix
|
||
]
|
||
</code></pre>
|
||
<h2 id="usage-1"><a class="header" href="#usage-1">Usage</a></h2>
|
||
<h3 id="internal"><a class="header" href="#internal">Internal</a></h3>
|
||
<p>profiles/profile-category/my-profile.nix:</p>
|
||
<pre><code class="language-nix">{ ... }:
|
||
{
|
||
services.MyService.enable = true;
|
||
}
|
||
</code></pre>
|
||
<h3 id="external"><a class="header" href="#external">External</a></h3>
|
||
<p>flake.nix:</p>
|
||
<pre><code class="language-nix">{
|
||
# inputs omitted
|
||
|
||
outputs = { self, devos, nixpkgs, ... }: {
|
||
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
|
||
system = "...";
|
||
|
||
modules = [
|
||
devos.nixosModules.my-service
|
||
({ ... }: {
|
||
services.MyService.enable = true;
|
||
})
|
||
];
|
||
};
|
||
};
|
||
}
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="overlays"><a class="header" href="#overlays">Overlays</a></h1>
|
||
<p>Writing overlays is a common occurence when using a NixOS system. Therefore,
|
||
we want to keep the process as simple and straightforward as possible.</p>
|
||
<p>Any <em>.nix</em> files declared in this directory will be assumed to be a valid
|
||
overlay, and will be automatically imported into all <a href="outputs/../concepts/hosts.html">hosts</a>, and
|
||
exported via <code>overlays.<channel>/<pkgName></code> <em>as well as</em>
|
||
<code>packages.<system>.<pkgName></code> (for valid systems), so all you have to do is
|
||
write it.</p>
|
||
<h2 id="example-3"><a class="header" href="#example-3">Example</a></h2>
|
||
<p>overlays/kakoune.nix:</p>
|
||
<pre><code class="language-nix">final: prev: {
|
||
kakoune = prev.kakoune.override {
|
||
configure.plugins = with final.kakounePlugins; [
|
||
(kak-fzf.override { fzf = final.skim; })
|
||
kak-auto-pairs
|
||
kak-buffers
|
||
kak-powerline
|
||
kak-vertical-selection
|
||
];
|
||
};
|
||
}
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="packages-1"><a class="header" href="#packages-1">Packages</a></h1>
|
||
<p>Similar to <a href="outputs/./modules.html">modules</a>, the pkgs directory mirrors the upstream
|
||
<a href="https://github.com/NixOS/nixpkgs/tree/master/pkgs">nixpkgs/pkgs</a>, and for the same reason; if you ever want to upstream
|
||
your package, it's as simple as dropping it into the nixpkgs/pkgs directory.</p>
|
||
<p>The only minor difference is that, instead of adding the <code>callPackage</code> call to
|
||
<code>all-packages.nix</code>, you just add it the the <em>default.nix</em> in this directory,
|
||
which is defined as a simple overlay.</p>
|
||
<p>All the packages are exported via <code>packages.<system>.<pkg-name></code>, for all
|
||
the supported systems listed in the package's <code>meta.platforms</code> attribute.</p>
|
||
<p>And, as usual, every package in the overlay is also available to any NixOS
|
||
<a href="outputs/../concepts/hosts.html">host</a>.</p>
|
||
<p>Another convenient difference is that it is possible to use
|
||
<a href="https://github.com/berberman/nvfetcher">nvfetcher</a> to keep packages up to
|
||
date.
|
||
This is best understood by the simple example below.</p>
|
||
<h2 id="example-4"><a class="header" href="#example-4">Example</a></h2>
|
||
<p>It is possible to specify sources separately to keep them up to date semi
|
||
automatically.
|
||
The basic rules are specified in pkgs/sources.toml:</p>
|
||
<pre><code class="language-toml"># nvfetcher.toml
|
||
[libinih]
|
||
src.github = "benhoyt/inih"
|
||
fetch.github = "benhoyt/inih"
|
||
</code></pre>
|
||
<p>After changes to this file as well as to update the packages specified in there run
|
||
nvfetcher (for more details see <a href="https://github.com/berberman/nvfetcher">nvfetcher</a>).</p>
|
||
<p>The pkgs overlay is managed in
|
||
pkgs/default.nix:</p>
|
||
<pre><code class="language-nix">final: prev: {
|
||
# keep sources first, this makes sources available to the pkgs
|
||
sources = prev.callPackage (import ./_sources/generated.nix) { };
|
||
|
||
# then, call packages with `final.callPackage`
|
||
libinih = prev.callPackage ./development/libraries/libinih { };
|
||
}
|
||
</code></pre>
|
||
<p>Lastly the example package is in
|
||
pkgs/development/libraries/libinih/default.nix:</p>
|
||
<pre><code class="language-nix">{ stdenv, meson, ninja, lib, sources, ... }:
|
||
stdenv.mkDerivation {
|
||
pname = "libinih";
|
||
|
||
# version will resolve to the latest available on gitub
|
||
inherit (sources.libinih) version src;
|
||
|
||
buildInputs = [ meson ninja ];
|
||
|
||
# ...
|
||
}
|
||
</code></pre>
|
||
<h2 id="migration-from-flake-based-approach"><a class="header" href="#migration-from-flake-based-approach">Migration from flake based approach</a></h2>
|
||
<p>Previous to nvfetcher it was possible to manage sources via a pkgs/flake.nix, the main changes from there are that sources where in the attribute "srcs" (now "sources") and the contents of the sources where slightly different.
|
||
In order to switch to the new system, rewrite pkgs/flake.nix to a pkgs/sources.toml file using the documentation of nvfetcher,
|
||
add the line that calls the sources at the beginning of pkgs/default.nix, and
|
||
accomodate the small changes in the packages as can be seen from the example.</p>
|
||
<p>The example package looked like:</p>
|
||
<p>pkgs/flake.nix:</p>
|
||
<pre><code class="language-nix">{
|
||
description = "Package sources";
|
||
|
||
inputs = {
|
||
libinih.url = "github:benhoyt/inih/r53";
|
||
libinih.flake = false;
|
||
};
|
||
}
|
||
</code></pre>
|
||
<p>pkgs/default.nix:</p>
|
||
<pre><code class="language-nix">final: prev: {
|
||
# then, call packages with `final.callPackage`
|
||
libinih = prev.callPackage ./development/libraries/libinih { };
|
||
}
|
||
</code></pre>
|
||
<p>pkgs/development/libraries/libinih/default.nix:</p>
|
||
<pre><code class="language-nix">{ stdenv, meson, ninja, lib, srcs, ... }:
|
||
let inherit (srcs) libinih; in
|
||
stdenv.mkDerivation {
|
||
pname = "libinih";
|
||
|
||
# version will resolve to 53, as specified in the flake.nix file
|
||
inherit (libinih) version;
|
||
|
||
src = libinih;
|
||
|
||
buildInputs = [ meson ninja ];
|
||
|
||
# ...
|
||
}
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="secrets"><a class="header" href="#secrets">Secrets</a></h1>
|
||
<p>Secrets are managed using <a href="https://github.com/ryantm/agenix">agenix</a>
|
||
so you can keep your flake in a public repository like GitHub without
|
||
exposing your password or other sensitive data.</p>
|
||
<h2 id="agenix"><a class="header" href="#agenix">Agenix</a></h2>
|
||
<p>Currently, there is <a href="https://github.com/NixOS/nix/issues/8">no mechanism</a> in nix itself to deploy secrets
|
||
within the nix store because it is world-readable.</p>
|
||
<p>Most NixOS modules have the ability to set options to files in the system, outside
|
||
the nix store, that contain sensitive information. You can use <a href="https://github.com/ryantm/agenix">agenix</a>
|
||
to easily setup those secret files declaratively.</p>
|
||
<p><a href="https://github.com/ryantm/agenix">agenix</a> encrypts secrets and stores them as .age files in your repository.
|
||
Age files are encrypted with multiple ssh public keys, so any host or user with a
|
||
matching ssh private key can read the data. The <a href="https://github.com/ryantm/agenix/blob/master/modules/age.nix">age module</a> will add those
|
||
encrypted files to the nix store and decrypt them on activation to <code>/run/secrets</code>.</p>
|
||
<h3 id="setup"><a class="header" href="#setup">Setup</a></h3>
|
||
<p>All hosts must have openssh enabled, this is done by default in the core profile.</p>
|
||
<p>You need to populate your <code>secrets/secrets.nix</code> with the proper ssh public keys.
|
||
Be extra careful to make sure you only add public keys, you should never share a
|
||
private key!!</p>
|
||
<p>secrets/secrets.nix:</p>
|
||
<pre><code class="language-nix">let
|
||
system = "<system ssh key>";
|
||
user = "<user ssh key>";
|
||
allKeys = [ system user ];
|
||
in
|
||
</code></pre>
|
||
<p>On most systems, you can get your systems ssh public key from <code>/etc/ssh/ssh_host_ed25519_key.pub</code>. If
|
||
this file doesn't exist you likely need to enable openssh and rebuild your system.</p>
|
||
<p>Your users ssh public key is probably stored in <code>~/.ssh/id_ed25519.pub</code> or
|
||
<code>~/.ssh/id_rsa.pub</code>. If you haven't generated a ssh key yet, be sure do so:</p>
|
||
<pre><code class="language-sh">ssh-keygen -t ed25519
|
||
</code></pre>
|
||
<blockquote>
|
||
<h5 id="note-4"><a class="header" href="#note-4"><em>Note:</em></a></h5>
|
||
<p>The underlying tool used by agenix, rage, doesn't work well with password protected
|
||
ssh keys. So if you have lots of secrets you might have to type in your password many
|
||
times.</p>
|
||
</blockquote>
|
||
<h3 id="secrets-1"><a class="header" href="#secrets-1">Secrets</a></h3>
|
||
<p>You will need the <code>agenix</code> command to create secrets. DevOS conveniently provides that
|
||
in the devShell, so just run <code>nix develop</code> whenever you want to edit secrets. Make sure
|
||
to always run <code>agenix</code> while in the <code>secrets/</code> folder, so it can pick up your <code>secrets.nix</code>.</p>
|
||
<p>To create secrets, simply add lines to your <code>secrets/secrets.nix</code>:</p>
|
||
<pre><code>let
|
||
...
|
||
allKeys = [ system user ];
|
||
in
|
||
{
|
||
"secret.age".publicKeys = allKeys;
|
||
}
|
||
</code></pre>
|
||
<p>That would tell agenix to create a <code>secret.age</code> file that is encrypted with the <code>system</code>
|
||
and <code>user</code> ssh public key.</p>
|
||
<p>Then go into the <code>secrets</code> folder and run:</p>
|
||
<pre><code class="language-sh">agenix -e secret.age
|
||
</code></pre>
|
||
<p>This will create the <code>secret.age</code>, if it doesn't already exist, and allow you to edit it.</p>
|
||
<p>If you ever change the <code>publicKeys</code> entry of any secret make sure to rekey the secrets:</p>
|
||
<pre><code class="language-sh">agenix --rekey
|
||
</code></pre>
|
||
<h3 id="usage-2"><a class="header" href="#usage-2">Usage</a></h3>
|
||
<p>Once you have your secret file encrypted and ready to use, you can utilize the <a href="https://github.com/ryantm/agenix/blob/master/modules/age.nix">age module</a>
|
||
to ensure that your secrets end up in <code>/run/secrets</code>.</p>
|
||
<p>In any profile that uses a NixOS module that requires a secret you can enable a particular secret like so:</p>
|
||
<pre><code class="language-nix">{ self, ... }:
|
||
{
|
||
age.secrets.mysecret.file = "${self}/secrets/mysecret.age";
|
||
}
|
||
</code></pre>
|
||
<p>Then you can just pass the path <code>/run/secrets/mysecret</code> to the module.</p>
|
||
<p>You can make use of the many options provided by the age module to customize where and how
|
||
secrets get decrypted. You can learn about them by looking at the
|
||
<a href="https://github.com/ryantm/agenix/blob/master/modules/age.nix">age module</a>.</p>
|
||
<blockquote>
|
||
<h5 id="note-5"><a class="header" href="#note-5"><em>Note:</em></a></h5>
|
||
<p>You can take a look at the <a href="https://github.com/ryantm/agenix">agenix repository</a> for more information
|
||
about the tool.</p>
|
||
</blockquote>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="testing"><a class="header" href="#testing">Testing</a></h1>
|
||
<p>Testing is always an important aspect of any software development project, and
|
||
NixOS offers some incredibly powerful tools to write tests for your
|
||
configuration, and, optionally, run them in
|
||
<a href="./integrations/hercules.html">CI</a>.</p>
|
||
<h2 id="unit-tests"><a class="header" href="#unit-tests">Unit Tests</a></h2>
|
||
<p>Unit tests can be created from regular derivations, and they can do
|
||
almost anything you can imagine. By convention, it is best to test your
|
||
packages during their <a href="https://nixos.org/manual/nixpkgs/stable/#ssec-check-phase">check phase</a>. All packages and their tests will
|
||
be built during CI.</p>
|
||
<h2 id="integration-tests"><a class="header" href="#integration-tests">Integration Tests</a></h2>
|
||
<p>All your profiles defined in suites will be tested in a NixOS VM.</p>
|
||
<p>You can write integration tests for one or more NixOS VMs that can,
|
||
optionally, be networked together, and yes, it's as awesome as it sounds!</p>
|
||
<p>Be sure to use the <code>mkTest</code> function from digga, <code>digga.lib.pkgs-lib.mkTest</code>
|
||
which wraps the official <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/lib/testing-python.nix">testing-python</a> function to ensure
|
||
that the system is setup exactly as it is for a bare DevOS system. There are
|
||
already great resources for learning how to use these tests effectively,
|
||
including the official <a href="https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests">docs</a>, a fantastic <a href="https://www.haskellforall.com/2020/11/how-to-use-nixos-for-lightweight.html">blog post</a>,
|
||
and the examples in <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixpkgs</a>.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="a-hrefhttpsgithubcomdivnixbudbuda-command"><a class="header" href="#a-hrefhttpsgithubcomdivnixbudbuda-command"><a href="https://github.com/divnix/bud"><code>bud</code></a> command</a></h1>
|
||
<p>The template incudes a convenient script for managing your system called <a href="https://github.com/divnix/bud"><code>bud</code></a>.</p>
|
||
<p>It is a portable and highly composable system control tool that work anywhere on your host
|
||
or in the flake's devshell. </p>
|
||
<p>Although it comes with some predefined standard helpers,
|
||
it is very extensible and you are encouraged to write your own script snippets
|
||
to ease your workflows. An example is the bud module for a <code>get</code> command that
|
||
comes included with <code>devos</code>.</p>
|
||
<p>While writing scripts you can convenientely access smart environment variables
|
||
that can tell the current architecture, user or host name, among others, regardless
|
||
wether you invoke <code>bud</code> within the devshell or as the system-wide installed <code>bud</code>.</p>
|
||
<p>For details, please review the <a href="https://github.com/divnix/bud">bud repo</a>.</p>
|
||
<h2 id="usage-3"><a class="header" href="#usage-3">Usage</a></h2>
|
||
<pre><code class="language-sh">bud help
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="get"><a class="header" href="#get">get</a></h1>
|
||
<p>The <code>get</code> subcommand is useful for getting a bare copy of devos without the
|
||
git history.</p>
|
||
<h2 id="usage-4"><a class="header" href="#usage-4">Usage</a></h2>
|
||
<pre><code class="language-sh">bud get DEST-DIR
|
||
</code></pre>
|
||
<p>If DEST-DIR is ommitted, it defaults to <em>./devos</em>.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="integrations"><a class="header" href="#integrations">Integrations</a></h1>
|
||
<p>This section explores some of the optional tools included with devos to provide
|
||
a solution to common concerns such as ci and remote deployment. An effort is
|
||
made to choose tools that treat nix, and where possible flakes, as first class
|
||
citizens.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="cachix"><a class="header" href="#cachix">Cachix</a></h1>
|
||
<p>The system will automatically pull a cachix.nix at the root if one exists.
|
||
This is usually created automatically by a <code>sudo cachix use</code>. If you're more
|
||
inclined to keep the root clean, you can drop any generated files in the
|
||
<code>cachix</code> directory into the <code>profiles/cachix</code> directory without further
|
||
modification.</p>
|
||
<p>For example, to add your own cache, assuming the template lives in /etc/nixos,
|
||
by simply running <code>sudo cachix use yourcache</code>. Then, optionally, move
|
||
<code>cachix/yourcache.nix</code> to <code>profiles/cachix/yourcache.nix</code></p>
|
||
<p>These caches are only added to the system after a <code>nixos-rebuild switch</code>, so it
|
||
is recommended to call <code>cachix use nrdxp</code> before the initial deployment, as it
|
||
will save a lot of build time.</p>
|
||
<p>In the future, users will be able to skip this step once the ability to define
|
||
the nix.conf within the flake is fully fleshed out upstream.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="deploy-rs"><a class="header" href="#deploy-rs">deploy-rs</a></h1>
|
||
<p><a href="https://github.com/serokell/deploy-rs">Deploy-rs</a> is a tool for managing NixOS remote machines. It was
|
||
chosen for devos after the author experienced some frustrations with the
|
||
stateful nature of nixops' db. It was also designed from scratch to support
|
||
flake based deployments, and so is an excellent tool for the job.</p>
|
||
<p>By default, all the <a href="integrations/../concepts/hosts.html">hosts</a> are also available as deploy-rs nodes,
|
||
configured with the hostname set to <code>networking.hostName</code>; overridable via
|
||
the command line.</p>
|
||
<h2 id="usage-5"><a class="header" href="#usage-5">Usage</a></h2>
|
||
<p>Just add your ssh key to the host:</p>
|
||
<pre><code class="language-nix">{ ... }:
|
||
{
|
||
users.users.${sshUser}.openssh.authorizedKeys.keyFiles = [
|
||
../secrets/path/to/key.pub
|
||
];
|
||
}
|
||
</code></pre>
|
||
<p>And the private key to your user:</p>
|
||
<pre><code class="language-nix">{ ... }:
|
||
{
|
||
home-manager.users.${sshUser}.programs.ssh = {
|
||
enable = true;
|
||
|
||
matchBlocks = {
|
||
${host} = {
|
||
host = hostName;
|
||
identityFile = ../secrets/path/to/key;
|
||
extraOptions = { AddKeysToAgent = "yes"; };
|
||
};
|
||
};
|
||
}
|
||
}
|
||
</code></pre>
|
||
<p>And run the deployment:</p>
|
||
<pre><code class="language-sh">deploy '.#hostName' --hostname host.example.com
|
||
</code></pre>
|
||
<blockquote>
|
||
<h5 id="note-6"><a class="header" href="#note-6"><em>Note:</em></a></h5>
|
||
<p>Your user will need <strong>passwordless</strong> sudo access</p>
|
||
</blockquote>
|
||
<h3 id="home-manager-1"><a class="header" href="#home-manager-1">Home Manager</a></h3>
|
||
<p>Digga's <code>lib.mkDeployNodes</code> provides only <code>system</code> profile.
|
||
In order to deploy your <code>home-manager</code> configuration you should provide additional profile(s) to deploy-rs config:</p>
|
||
<pre><code class="language-nix"># Initially, this line looks like this: deploy.nodes = digga.lib.mkDeployNodes self.nixosConfigurations { };
|
||
deploy.nodes = digga.lib.mkDeployNodes self.nixosConfigurations
|
||
{
|
||
<HOSTNAME> = {
|
||
profilesOrder = [ "system" "<HM_PROFILE>" "<ANOTHER_HM_PROFILE>"];
|
||
profiles.<HM_PROFILE> = {
|
||
user = "<YOUR_USERNAME>";
|
||
path = deploy.lib.x86_64-linux.activate.home-manager self.homeConfigurationsPortable.x86_64-linux.<YOUR_USERNAME>;
|
||
};
|
||
profiles.<ANOTHER_HM_PROFILE> = {
|
||
user = "<ANOTHER_USERNAME>";
|
||
path = deploy.lib.x86_64-linux.activate.home-manager self.homeConfigurationsPortable.x86_64-linux.<ANOTHER_USERNAME>;
|
||
};
|
||
};
|
||
};
|
||
</code></pre>
|
||
<p>Substitute <code><HOSTNAME></code>, <code><HM_PROFILE></code> and <code><YOUR_USERNAME></code> placeholders (omitting the <code><></code>). </p>
|
||
<p><code><ANOTHER_HM_PROFILE></code> is there to illustrate deploying multiple <code>home-manager</code> configurations. Either substitute those as well,
|
||
or remove them altogether. Don't forget the <code>profileOrder</code> variable.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="nvfetcher"><a class="header" href="#nvfetcher">nvfetcher</a></h1>
|
||
<p><a href="https://github.com/berberman/nvfetcher">NvFetcher</a> is a workflow companion for updating nix sources.</p>
|
||
<p>You can specify an origin source and an update configuration, and
|
||
nvfetcher can for example track updates to a specific branch and
|
||
automatically update your nix sources configuration on each run
|
||
to the tip of that branch.</p>
|
||
<p>All package source declaration is done in <a href="https://github.com/divnix/devos/tree/main/pkgs/sources.toml">sources.toml</a>.</p>
|
||
<p>From within the devshell of this repo, run <code>nvfetcher</code>, a wrapped
|
||
version of <code>nvfetcher</code> that knows where to find and place its files
|
||
and commit the results.</p>
|
||
<h2 id="usage-6"><a class="header" href="#usage-6">Usage</a></h2>
|
||
<p>Statically fetching (not tracking) a particular tag from a github repo:</p>
|
||
<pre><code class="language-toml">[manix]
|
||
src.manual = "v0.6.3"
|
||
fetch.github = "mlvzk/manix"
|
||
</code></pre>
|
||
<p>Tracking the latest github <em>release</em> from a github repo:</p>
|
||
<pre><code class="language-toml">[manix]
|
||
src.github = "mlvzk/manix" # responsible for tracking
|
||
fetch.github = "mlvzk/manix" # responsible for fetching
|
||
</code></pre>
|
||
<p>Tracking the latest commit of a git repository and fetch from a git repo:</p>
|
||
<pre><code class="language-toml">[manix]
|
||
src.git = "https://github.com/mlvzk/manix.git" # responsible for tracking
|
||
fetch.git = "https://github.com/mlvzk/manix.git" # responsible for fetching
|
||
</code></pre>
|
||
<blockquote>
|
||
<h5 id="note-7"><a class="header" href="#note-7"><em>Note:</em></a></h5>
|
||
<p>Please refer to the <a href="https://github.com/berberman/nvfetcher#readme">NvFetcher Readme</a> for more options.</p>
|
||
</blockquote>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="hercules-ci"><a class="header" href="#hercules-ci">Hercules CI</a></h1>
|
||
<p>If you start adding your own packages and configurations, you'll probably have
|
||
at least a few binary artifacts. With hercules we can build every package in
|
||
our configuration automatically, on every commit. Additionally, we can have it
|
||
upload all our build artifacts to a binary cache like <a href="https://cachix.org">cachix</a>.</p>
|
||
<p>This will work whether your copy is a fork, or a bare template, as long as your
|
||
repo is hosted on GitHub.</p>
|
||
<h2 id="setup-1"><a class="header" href="#setup-1">Setup</a></h2>
|
||
<p>Just head over to <a href="https://hercules-ci.com">hercules-ci.com</a> to make an account.</p>
|
||
<p>Then follow the docs to set up an <a href="https://docs.hercules-ci.com/hercules-ci/getting-started/#github">agent</a>, if you want to deploy to a
|
||
binary cache (and of course you do), be sure <em>not</em> to skip the
|
||
<a href="https://docs.hercules-ci.com/hercules-ci/getting-started/deploy/nixos/#_3_configure_a_binary_cache">binary-caches.json</a>.</p>
|
||
<h2 id="ready-to-use"><a class="header" href="#ready-to-use">Ready to Use</a></h2>
|
||
<p>The repo is already set up with the proper <em>default.nix</em> file, building all
|
||
declared packages, checks, profiles and shells. So you can see if something
|
||
breaks, and never build the same package twice!</p>
|
||
<p>If you want to get fancy, you could even have hercules
|
||
<a href="https://docs.hercules-ci.com/hercules-ci-effects/guide/deploy-a-nixos-machine/">deploy your configuration</a>!</p>
|
||
<blockquote>
|
||
<h5 id="note-8"><a class="header" href="#note-8"><em>Note:</em></a></h5>
|
||
<p>Hercules doesn't have access to anything encrypted in the
|
||
<a href="integrations/../../secrets">secrets folder</a>, so none of your secrets will accidentally get
|
||
pushed to a cache by mistake.</p>
|
||
<p>You could pull all your secrets via your user, and then exclude it from
|
||
<a href="https://github.com/nrdxp/devos/blob/nrd/suites/default.nix#L17">allUsers</a>
|
||
to keep checks passing.</p>
|
||
</blockquote>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="pull-requests"><a class="header" href="#pull-requests">Pull Requests</a></h1>
|
||
<h2 id="tldr"><a class="header" href="#tldr">TL;DR;</a></h2>
|
||
<ul>
|
||
<li><strong>Target Branch</strong>: <code>main</code></li>
|
||
<li><strong>Merge Policy</strong>: <a href="https://bors.tech"><code>bors</code></a> is always right (→ <code>bors try</code>)</li>
|
||
<li><strong>Docs</strong>: every changeset is expected to contain doc updates</li>
|
||
<li><strong>Commit Msg</strong>: be a poet! Comprehensive and explanatory commit messages
|
||
should cover the motivation and use case in an easily understandable manner
|
||
even when read after a few months.</li>
|
||
<li><strong>Test Driven Development</strong>: please default to test driven development where possible.</li>
|
||
</ul>
|
||
<h3 id="within-the-devshell-nix-develop"><a class="header" href="#within-the-devshell-nix-develop">Within the Devshell (<code>nix develop</code>)</a></h3>
|
||
<ul>
|
||
<li><strong>Hooks</strong>: please <code>git commit</code> within the devshell</li>
|
||
<li><strong>Fail Early</strong>: please run from within the devshell on your local machine:
|
||
<ul>
|
||
<li><code>nix flake check</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
<script type="text/javascript">
|
||
window.playground_copyable = true;
|
||
</script>
|
||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
<script type="text/javascript">
|
||
window.addEventListener('load', function() {
|
||
window.setTimeout(window.print, 100);
|
||
});
|
||
</script>
|
||
</body>
|
||
</html>
|