pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="sec-installation">
6
7<title>Installing NixOS</title>
8
9<orderedlist>
10
11 <listitem><para>Boot from the CD.</para></listitem>
12
13 <listitem><para>The CD contains a basic NixOS installation. (It
14 also contains Memtest86+, useful if you want to test new hardware).
15 When it’s finished booting, it should have detected most of your
16 hardware.</para></listitem>
17
18 <listitem><para>The NixOS manual is available on virtual console 8
19 (press Alt+F8 to access).</para></listitem>
20
21 <listitem><para>You get logged in as <literal>root</literal>
22 (with empty password).</para></listitem>
23
24 <listitem><para>If you downloaded the graphical ISO image, you can
25 run <command>start display-manager</command> to start KDE.</para></listitem>
26
27 <listitem><para>The boot process should have brought up networking (check
28 <command>ip a</command>). Networking is necessary for the
29 installer, since it will download lots of stuff (such as source
30 tarballs or Nixpkgs channel binaries). It’s best if you have a DHCP
31 server on your network. Otherwise configure networking manually
32 using <command>ifconfig</command>.</para>
33 <para>To manually configure the network on the graphical installer,
34 first disable network-manager with
35 <command>systemctl stop network-manager</command>.</para></listitem>
36
37 <listitem><para>The NixOS installer doesn’t do any partitioning or
38 formatting yet, so you need to do that yourself. Use the following
39 commands:
40
41 <itemizedlist>
42
43 <listitem><para>For partitioning:
44 <command>fdisk</command>.</para></listitem>
45
46 <listitem><para>For initialising Ext4 partitions:
47 <command>mkfs.ext4</command>. It is recommended that you assign a
48 unique symbolic label to the file system using the option
49 <option>-L <replaceable>label</replaceable></option>, since this
50 makes the file system configuration independent from device
51 changes. For example:
52
53<screen>
54$ mkfs.ext4 -L nixos /dev/sda1</screen>
55
56 </para></listitem>
57
58 <listitem><para>For creating swap partitions:
59 <command>mkswap</command>. Again it’s recommended to assign a
60 label to the swap partition: <option>-L
61 <replaceable>label</replaceable></option>.</para></listitem>
62
63 <listitem><para>For creating LVM volumes, the LVM commands, e.g.,
64
65<screen>
66$ pvcreate /dev/sda1 /dev/sdb1
67$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1
68$ lvcreate --size 2G --name bigdisk MyVolGroup
69$ lvcreate --size 1G --name smalldisk MyVolGroup</screen>
70
71 </para></listitem>
72
73 <listitem><para>For creating software RAID devices, use
74 <command>mdadm</command>.</para></listitem>
75
76 </itemizedlist>
77
78 </para></listitem>
79
80 <listitem><para>Mount the target file system on which NixOS should
81 be installed on <filename>/mnt</filename>, e.g.
82
83<screen>
84$ mount /dev/disk/by-label/nixos /mnt
85</screen>
86
87 </para></listitem>
88
89 <listitem><para>If your machine has a limited amount of memory, you
90 may want to activate swap devices now (<command>swapon
91 <replaceable>device</replaceable></command>). The installer (or
92 rather, the build actions that it may spawn) may need quite a bit of
93 RAM, depending on your configuration.</para></listitem>
94
95 <listitem>
96
97 <para>You now need to create a file
98 <filename>/mnt/etc/nixos/configuration.nix</filename> that
99 specifies the intended configuration of the system. This is
100 because NixOS has a <emphasis>declarative</emphasis> configuration
101 model: you create or edit a description of the desired
102 configuration of your system, and then NixOS takes care of making
103 it happen. The syntax of the NixOS configuration file is
104 described in <xref linkend="sec-configuration-syntax"/>, while a
105 list of available configuration options appears in <xref
106 linkend="ch-options"/>. A minimal example is shown in <xref
107 linkend="ex-config"/>.</para>
108
109 <para>The command <command>nixos-generate-config</command> can
110 generate an initial configuration file for you:
111
112<screen>
113$ nixos-generate-config --root /mnt</screen>
114
115 You should then edit
116 <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your
117 needs:
118
119<screen>
120$ nano /mnt/etc/nixos/configuration.nix
121</screen>
122
123 If you’re using the graphical ISO image, other editors may be
124 available (such as <command>vim</command>). If you have network
125 access, you can also install other editors — for instance, you can
126 install Emacs by running <literal>nix-env -i
127 emacs</literal>.</para>
128
129 <para>You <emphasis>must</emphasis> set the option
130 <option>boot.loader.grub.device</option> to specify on which disk
131 the GRUB boot loader is to be installed. Without it, NixOS cannot
132 boot.</para>
133
134 <para>Another critical option is <option>fileSystems</option>,
135 specifying the file systems that need to be mounted by NixOS.
136 However, you typically don’t need to set it yourself, because
137 <command>nixos-generate-config</command> sets it automatically in
138 <filename>/mnt/etc/nixos/hardware-configuration.nix</filename>
139 from your currently mounted file systems. (The configuration file
140 <filename>hardware-configuration.nix</filename> is included from
141 <filename>configuration.nix</filename> and will be overwritten by
142 future invocations of <command>nixos-generate-config</command>;
143 thus, you generally should not modify it.)</para>
144
145 <note><para>Depending on your hardware configuration or type of
146 file system, you may need to set the option
147 <option>boot.initrd.kernelModules</option> to include the kernel
148 modules that are necessary for mounting the root file system,
149 otherwise the installed system will not be able to boot. (If this
150 happens, boot from the CD again, mount the target file system on
151 <filename>/mnt</filename>, fix
152 <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun
153 <filename>nixos-install</filename>.) In most cases,
154 <command>nixos-generate-config</command> will figure out the
155 required modules.</para></note>
156
157 <para>Examples of real-world NixOS configuration files can be
158 found at <link
159 xlink:href="https://nixos.org/repos/nix/configurations/trunk/"/>.</para>
160
161 </listitem>
162
163 <listitem><para>Do the installation:
164
165<screen>
166$ nixos-install</screen>
167
168 Cross fingers. If this fails due to a temporary problem (such as
169 a network issue while downloading binaries from the NixOS binary
170 cache), you can just re-run <command>nixos-install</command>.
171 Otherwise, fix your <filename>configuration.nix</filename> and
172 then re-run <command>nixos-install</command>.</para>
173
174 <para>As the last step, <command>nixos-install</command> will ask
175 you to set the password for the <literal>root</literal> user, e.g.
176
177<screen>
178setting root password...
179Enter new UNIX password: ***
180Retype new UNIX password: ***
181</screen>
182
183 </para>
184
185 </listitem>
186
187 <listitem><para>If everything went well:
188
189<screen>
190$ reboot</screen>
191
192 </para></listitem>
193
194 <listitem>
195
196 <para>You should now be able to boot into the installed NixOS. The
197 GRUB boot menu shows a list of <emphasis>available
198 configurations</emphasis> (initially just one). Every time you
199 change the NixOS configuration (see <link
200 linkend="sec-changing-config">Changing Configuration</link> ), a
201 new item is added to the menu. This allows you to easily roll back
202 to a previous configuration if something goes wrong.</para>
203
204 <para>You should log in and change the <literal>root</literal>
205 password with <command>passwd</command>.</para>
206
207 <para>You’ll probably want to create some user accounts as well,
208 which can be done with <command>useradd</command>:
209
210<screen>
211$ useradd -c 'Eelco Dolstra' -m eelco
212$ passwd eelco</screen>
213
214 </para>
215
216 <para>You may also want to install some software. For instance,
217
218<screen>
219$ nix-env -qa \*</screen>
220
221 shows what packages are available, and
222
223<screen>
224$ nix-env -i w3m</screen>
225
226 install the <literal>w3m</literal> browser.</para>
227
228 </listitem>
229
230</orderedlist>
231
232<para>To summarise, <xref linkend="ex-install-sequence" /> shows a
233typical sequence of commands for installing NixOS on an empty hard
234drive (here <filename>/dev/sda</filename>). <xref linkend="ex-config"
235/> shows a corresponding configuration Nix expression.</para>
236
237<example xml:id='ex-install-sequence'><title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>
238<screen>
239$ fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
240$ mkfs.ext4 -L nixos /dev/sda1
241$ mkswap -L swap /dev/sda2
242$ swapon /dev/sda2
243$ mount /dev/disk/by-label/nixos /mnt
244$ nixos-generate-config --root /mnt
245$ nano /mnt/etc/nixos/configuration.nix
246$ nixos-install
247$ reboot</screen>
248</example>
249
250<example xml:id='ex-config'><title>NixOS Configuration</title>
251<screen>
252{ config, pkgs, ... }:
253
254{
255 imports =
256 [ # Include the results of the hardware scan.
257 ./hardware-configuration.nix
258 ];
259
260 boot.loader.grub.device = "/dev/sda";
261
262 # Note: setting fileSystems is generally not
263 # necessary, since nixos-generate-config figures them out
264 # automatically in hardware-configuration.nix.
265 #fileSystems."/".device = "/dev/disk/by-label/nixos";
266
267 # Enable the OpenSSH server.
268 services.sshd.enable = true;
269}</screen>
270</example>
271
272<xi:include href="installing-uefi.xml" />
273<xi:include href="installing-usb.xml" />
274
275</chapter>