pyrox.dev
1<!-- vim: set expandtab ts=2 softtabstop=2 shiftwidth=2 smarttab textwidth=80 wrapmargin=2 -->
2<section
3 xmlns="http://docbook.org/ns/docbook"
4 xmlns:xlink="http://www.w3.org/1999/xlink"
5 xmlns:xi="http://www.w3.org/2001/XInclude"
6 version="5.0"
7 xml:id="sec-installing-from-other-distro">
8
9 <title>Installing from another Linux distribution</title>
10
11 <para>
12 Because Nix (the package manager) & Nixpkgs (the Nix packages
13 collection) can both be installed on any (most?) Linux distributions,
14 they can be used to install NixOS in various creative ways. You can,
15 for instance:
16 </para>
17
18 <orderedlist>
19 <listitem><para>Install NixOS on another partition, from your existing
20 Linux distribution (without the use of a USB or optical
21 device!)</para></listitem>
22
23 <listitem><para>Install NixOS on the same partition (in place!), from
24 your existing non-NixOS Linux distribution using
25 <literal>NIXOS_LUSTRATE</literal>.</para></listitem>
26
27 <listitem><para>Install NixOS on your hard drive from the Live CD of
28 any Linux distribution.</para></listitem>
29 </orderedlist>
30
31 <para>The first steps to all these are the same:</para>
32
33 <orderedlist>
34 <listitem>
35 <para>Install the Nix package manager:</para>
36
37 <para>Short version:</para>
38
39 <screen>
40$ bash <(curl https://nixos.org/nix/install)
41$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen>
42
43 <para>More details in the <link
44 xlink:href="https://nixos.org/nix/manual/#chap-quick-start">
45 Nix manual</link></para>
46 </listitem>
47
48 <listitem>
49 <para>Switch to the NixOS channel:</para>
50
51 <para>If you've just installed Nix on a non-NixOS distribution, you
52 will be on the <literal>nixpkgs</literal> channel by
53 default.</para>
54
55 <screen>
56$ nix-channel --list
57nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen>
58
59 <para>As that channel gets released without running the NixOS
60 tests, it will be safer to use the <literal>nixos-*</literal>
61 channels instead:</para>
62
63 <screen>
64$ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen>
65
66 <para>You may want to throw in a <literal>nix-channel
67 --update</literal> for good measure.</para>
68 </listitem>
69
70 <listitem>
71 <para>Install the NixOS installation tools:</para>
72
73 <para>You'll need <literal>nixos-generate-config</literal> and
74 <literal>nixos-install</literal> and we'll throw in some man
75 pages and <literal>nixos-enter</literal> just in case you want
76 to chroot into your NixOS partition. They are installed by
77 default on NixOS, but you don't have NixOS yet..</para>
78
79 <screen>$ nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen>
80 </listitem>
81
82 <listitem>
83 <note><para>The following 5 steps are only for installing NixOS to
84 another partition. For installing NixOS in place using
85 <literal>NIXOS_LUSTRATE</literal>, skip ahead.</para></note>
86
87 <para>Prepare your target partition:</para>
88
89 <para>At this point it is time to prepare your target partition.
90 Please refer to the partitioning, file-system creation, and
91 mounting steps of <xref linkend="sec-installation" /></para>
92
93 <para>If you're about to install NixOS in place using
94 <literal>NIXOS_LUSTRATE</literal> there is nothing to do for
95 this step.</para>
96 </listitem>
97
98 <listitem>
99 <para>Generate your NixOS configuration:</para>
100
101 <screen>$ sudo `which nixos-generate-config` --root /mnt</screen>
102
103 <para>You'll probably want to edit the configuration files. Refer
104 to the <literal>nixos-generate-config</literal> step in <xref
105 linkend="sec-installation" /> for more information.</para>
106
107 <para>Consider setting up the NixOS bootloader to give you the
108 ability to boot on your existing Linux partition. For instance,
109 if you're using GRUB and your existing distribution is running
110 Ubuntu, you may want to add something like this to your
111 <literal>configuration.nix</literal>:</para>
112
113 <programlisting>
114boot.loader.grub.extraEntries = ''
115 menuentry "Ubuntu" {
116 search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
117 configfile "($ubuntu)/boot/grub/grub.cfg"
118 }
119'';</programlisting>
120
121 <para>(You can find the appropriate UUID for your partition in
122 <literal>/dev/disk/by-uuid</literal>)</para>
123 </listitem>
124
125 <listitem>
126 <para>Create the <literal>nixbld</literal> group and user on your
127 original distribution:</para>
128
129 <screen>
130$ sudo groupadd -g 30000 nixbld
131$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen>
132 </listitem>
133
134 <listitem>
135 <para>Download/build/install NixOS:</para>
136
137 <warning><para>Once you complete this step, you might no longer be
138 able to boot on existing systems without the help of a
139 rescue USB drive or similar.</para></warning>
140
141 <screen>$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen>
142
143 <para>Again, please refer to the <literal>nixos-install</literal>
144 step in <xref linkend="sec-installation" /> for more
145 information.</para>
146
147 <para>That should be it for installation to another partition!</para>
148 </listitem>
149
150 <listitem>
151 <para>Optionally, you may want to clean up your non-NixOS distribution:</para>
152
153 <screen>
154$ sudo userdel nixbld
155$ sudo groupdel nixbld</screen>
156
157 <para>If you do not wish to keep the Nix package mananager
158 installed either, run something like <literal>sudo rm -rv
159 ~/.nix-* /nix</literal> and remove the line that the Nix
160 installer added to your <literal>~/.profile</literal>.</para>
161 </listitem>
162
163 <listitem>
164 <note><para>The following steps are only for installing NixOS in
165 place using
166 <literal>NIXOS_LUSTRATE</literal>:</para></note>
167
168 <para>Generate your NixOS configuration:</para>
169
170 <screen>$ sudo `which nixos-generate-config` --root /</screen>
171
172 <para>Note that this will place the generated configuration files
173 in <literal>/etc/nixos</literal>. You'll probably want to edit
174 the configuration files. Refer to the
175 <literal>nixos-generate-config</literal> step in <xref
176 linkend="sec-installation" /> for more information.</para>
177
178 <para>You'll likely want to set a root password for your first boot
179 using the configuration files because you won't have a chance
180 to enter a password until after you reboot. You can initalize
181 the root password to an empty one with this line: (and of course
182 don't forget to set one once you've rebooted or to lock the
183 account with <literal>sudo passwd -l root</literal> if you use
184 <literal>sudo</literal>)</para>
185
186 <programlisting>users.extraUsers.root.initialHashedPassword = "";</programlisting>
187 </listitem>
188
189 <listitem>
190 <para>Build the NixOS closure and install it in the
191 <literal>system</literal> profile:</para>
192
193 <screen>$ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen>
194 </listitem>
195
196 <listitem>
197 <para>Change ownership of the <literal>/nix</literal> tree to root
198 (since your Nix install was probably single user):</para>
199
200 <screen>$ sudo chown -R 0.0 /nix</screen>
201 </listitem>
202
203 <listitem>
204 <para>Set up the <literal>/etc/NIXOS</literal> and
205 <literal>/etc/NIXOS_LUSTRATE</literal> files:</para>
206
207 <para><literal>/etc/NIXOS</literal> officializes that this is now a
208 NixOS partition (the bootup scripts require its presence).</para>
209
210 <para><literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup
211 scripts to move <emphasis>everything</emphasis> that's in the
212 root partition to <literal>/old-root</literal>. This will move
213 your existing distribution out of the way in the very early
214 stages of the NixOS bootup. There are exceptions (we do need to
215 keep NixOS there after all), so the NixOS lustrate process will
216 not touch:</para>
217
218 <itemizedlist>
219 <listitem><para>The <literal>/nix</literal>
220 directory</para></listitem>
221
222 <listitem><para>The <literal>/boot</literal>
223 directory</para></listitem>
224
225 <listitem><para>Any file or directory listed in
226 <literal>/etc/NIXOS_LUSTRATE</literal> (one per
227 line)</para></listitem>
228 </itemizedlist>
229
230 <para>Let's create the files:</para>
231
232 <screen>
233$ sudo touch /etc/NIXOS
234$ sudo touch /etc/NIXOS_LUSTRATE</screen>
235
236 <para>Let's also make sure the NixOS configuration files are kept
237 once we reboot on NixOS:</para>
238
239 <screen>
240$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE</screen>
241 </listitem>
242
243 <listitem>
244 <para>Finally, move the <literal>/boot</literal> directory of your
245 current distribution out of the way (the lustrate process will
246 take care of the rest once you reboot, but this one must be
247 moved out now because NixOS needs to install its own boot
248 files:</para>
249
250 <warning><para>Once you complete this step, your current
251 distribution will no longer be bootable! If you didn't get
252 all the NixOS configuration right, especially those
253 settings pertaining to boot loading and root partition,
254 NixOS may not be bootable either. Have a USB rescue device
255 ready in case this happens. </para></warning>
256
257 <screen>
258$ sudo mv -v /boot /boot.bak &&
259 sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot</screen>
260
261 <para>Cross your fingers, reboot, hopefully you should get a NixOS
262 prompt!</para>
263 </listitem>
264 <listitem>
265 <para>If for some reason you want to revert to the old
266 distribution, you'll need to boot on a USB rescue disk and do
267 something along these lines:</para>
268
269 <screen>
270# mkdir root
271# mount /dev/sdaX root
272# mkdir root/nixos-root
273# mv -v root/* root/nixos-root/
274# mv -v root/nixos-root/old-root/* root/
275# mv -v root/boot.bak root/boot # We had renamed this by hand earlier
276# umount root
277# reboot</screen>
278
279 <para>This may work as is or you might also need to reinstall the
280 boot loader</para>
281
282 <para>And of course, if you're happy with NixOS and no longer need
283 the old distribution:</para>
284
285 <screen>sudo rm -rf /old-root</screen>
286 </listitem>
287
288 <listitem>
289 <para>It's also worth noting that this whole process can be
290 automated. This is especially useful for Cloud VMs, where
291 provider do not provide NixOS. For instance, <link
292 xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link>
293 uses the lustrate process to convert Digital Ocean droplets to
294 NixOS from other distributions automatically.</para>
295 </listitem>
296 </orderedlist>
297</section>