diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/entities.ent | 22 | ||||
| -rw-r--r-- | doc/index.xml | 37 | ||||
| -rw-r--r-- | doc/install.xml | 80 | ||||
| -rw-r--r-- | doc/options.xml | 9 |
4 files changed, 148 insertions, 0 deletions
diff --git a/doc/entities.ent b/doc/entities.ent new file mode 100644 index 00000000..cee77e2d --- /dev/null +++ b/doc/entities.ent @@ -0,0 +1,22 @@ +<!ENTITY nixos.url "https://nixos.org/"> +<!ENTITY nixpkgs.url "https://nixos.org/nixpkgs/"> +<!ENTITY openlab.url "https://openlab-augsburg.de/"> + +<!ENTITY nixos ' +<link xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xlink:href="&nixos.url;">NixOS</link> +'> +<!ENTITY nixpkgs ' +<link xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xlink:href="&nixpkgs.url;"><nixpkgs></link> +'> +<!ENTITY openlab ' +<link xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xlink:href="&openlab.url;">OpenLab Augsburg</link> +'> + +<!ENTITY hydra.base "https://headcounter.org/hydra"> +<!ENTITY hydra.channelbase "&hydra.base;/channel/custom/openlab/vuizvui"> diff --git a/doc/index.xml b/doc/index.xml new file mode 100644 index 00000000..efb0bf2f --- /dev/null +++ b/doc/index.xml @@ -0,0 +1,37 @@ +<?xml version="1.0"?> +<!DOCTYPE book [ +<!ENTITY % entities SYSTEM "entities.ent"> +%entities; +]> +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <title>Vuizvui</title> + <preface> + <title>What is Vuizvui?</title> + <para> + Vuizvui is a set of NixOS modules and machine configurations that aim to + extend &nixos; in a way that fits the needs of the members of the + &openlab; and also serves as a playground for experimental features that + are yet to be included in the official NixOS project once they're well + tested and matured enough. + </para> + + <para> + This means that module options in Vuizvui are subject to change without + retaining backwards-compatibility for configurations outside of the + defined machines. + </para> + + <para> + The name <literal>Vuizvui</literal> is of Bavarian origins and means + something like <literal>too much</literal> while on the other side + <literal>nix</literal> means nothing. Which fits quite well because this + repository is for everything either too complex or not polished/generic + enough to be pushed into &nixpkgs;. + </para> + </preface> + + <xi:include href="install.xml" /> + <xi:include href="options.xml" /> +</book> diff --git a/doc/install.xml b/doc/install.xml new file mode 100644 index 00000000..df94a8f3 --- /dev/null +++ b/doc/install.xml @@ -0,0 +1,80 @@ +<?xml version="1.0"?> +<!DOCTYPE book [ +<!ENTITY % entities SYSTEM "entities.ent"> +%entities; +]> +<part xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <title>Installing a machine in Vuizvui</title> + + <para> + The easiest way to get started is if the machine is already in Vuizvui so + there is a channel available. + </para> + + <para> + You can have a look at + <link xlink:href="&hydra.base;/jobset/openlab/vuizvui#tabs-channels">the + list of channels</link> + to check whether a channel exists for the machine you want to install. + </para> + + <para> + So let's say you want to install the machine <literal>labtop</literal> which + has the channel attribute <literal>channels.machines.labnet.labtop</literal> + </para> + + <para> + First you need to add the channel for the + <systemitem class="username">root</systemitem> user of your current system + using the following commands: + + <command> +<screen> +nix-channel --add <link + xlink:href="&hydra.channelbase;/channels.machines.labnet.labtop"/> vuizvui +nix-channel --update +</screen> + </command> + + Notice the <literal>vuizvui</literal> argument at the end of the first + command. This makes the channel available as + <literal><vuizvui></literal> in the search path of the current system. + </para> + + <para> + For the first installation the <envar>NIX_PATH</envar> isn't correctly set + and will be set to include the <literal>vuizvui</literal> channel after + you've switched to the configuration for the first time. + </para> + + <para> + Next put the following in your + <filename>/etc/nixos/configuration.nix</filename>: + </para> + + <screen><code language="nix">(import <vuizvui/machines> {}).labnet.labtop.config</code></screen> + + <para> + Of course you need to replace <literal>labnet.labtop</literal> with the + attribute of your machine. + </para> + + <para> + Now in order to do the first build and activation of the configuration, you + need to issue the following command as root: + </para> + + <!-- FIXME: This WON'T work because of wrong NIX_PATH and missicg binary + cache public key! --> + <!-- TODO: create a bootsrap script that does this automatically --> + <screen><command>nixos-rebuild \ + -I nixpkgs=/nix/var/nix/profiles/per-user/root/channels/vuizvui/nixpkgs \ + --option binary-cache-public-keys "headcounter.org:/7YANMvnQnyvcVB6rgFTdb8p5LG1OTXaO+21CaOSBzg=" \ + switch</command></screen> + + <para> + We redefine <literal>nixpkgs</literal> here, because vuizvui brings its own nixpkgs that gets build on the hydra, using it we get to download from the binary cache. Additionally, we need to manually specify the public key for the <literal>headcounter.org</literal> hydra. + </para> +</part> diff --git a/doc/options.xml b/doc/options.xml new file mode 100644 index 00000000..da30e6c8 --- /dev/null +++ b/doc/options.xml @@ -0,0 +1,9 @@ +<part xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <title>Vuizvui-specific NixOS options</title> + <para> + The following NixOS options are specific to Vuizvui: + </para> + <xi:include href="options-db.xml" /> +</part> |