nixos doc: document the installation process from other distros as well as NIXOS_LUSTRATE

2 files changed, 298 insertions, 0 deletions

diff --git a/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml
new file mode 100644
index 000000000000..556238988274
--- /dev/null
+++ b/nixos/doc/manual/installation/installing-from-other-distro.xml
@@ -0,0 +1,297 @@
+<!-- vim: set expandtab ts=2 softtabstop=2 shiftwidth=2 smarttab textwidth=80 wrapmargin=2 -->
+<section
+    xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    version="5.0"
+    xml:id="sec-installing-from-other-distro">
+
+    <title>Installing from another Linux distribution</title>
+
+    <para>
+        Because Nix (the package manager) &amp; Nixpkgs (the Nix packages
+        collection) can both be installed on any (most?) Linux distributions,
+        they can be used to install NixOS in various creative ways. You can,
+        for instance:
+    </para>
+
+    <orderedlist>
+        <listitem><para>Install NixOS on another partition, from your existing
+                Linux distribution (without the use of a USB or optical
+                device!)</para></listitem>
+
+        <listitem><para>Install NixOS on the same partition (in place!), from
+                your existing non-NixOS Linux distribution using
+                <literal>NIXOS_LUSTRATE</literal>.</para></listitem>
+
+        <listitem><para>Install NixOS on your hard drive from the Live CD of
+                any Linux distribution.</para></listitem>
+    </orderedlist>
+
+    <para>The first steps to all these are the same:</para>
+
+    <orderedlist>
+        <listitem>
+            <para>Install the Nix package manager:</para>
+
+            <para>Short version:</para>
+
+            <screen>
+$ bash &lt;(curl https://nixos.org/nix/install)
+$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen>
+
+            <para>More details in the <link
+                    xlink:href="https://nixos.org/nix/manual/#chap-quick-start">
+                    Nix manual</link></para>
+        </listitem>
+
+        <listitem>
+            <para>Switch to the NixOS channel:</para>
+
+            <para>If you've just installed Nix on a non-NixOS distribution, you
+                will be on the <literal>nixpkgs</literal> channel by
+                default.</para>
+
+            <screen>
+$ nix-channel --list
+nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen>
+
+            <para>As that channel gets released without running the NixOS
+                tests, it will be safer to use the <literal>nixos-*</literal>
+                channels instead:</para>
+
+            <screen>
+$ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen>
+
+            <para>You may want to throw in a <literal>nix-channel
+                    --update</literal> for good measure.</para>
+        </listitem>
+
+        <listitem>
+            <para>Install the NixOS installation tools:</para>
+
+            <para>You'll need <literal>nixos-generate-config</literal> and
+                <literal>nixos-install</literal> and we'll throw in some man
+                pages and <literal>nixos-enter</literal> just in case you want
+                to chroot into your NixOS partition. They are installed by
+                default on NixOS, but you don't have NixOS yet..</para>
+
+            <screen>$ nix-env -iE "_: with import &lt;nixpkgs/nixos&gt; { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen>
+        </listitem>
+
+        <listitem>
+            <note><para>The following 5 steps are only for installing NixOS to
+                    another partition. For installing NixOS in place using
+                    <literal>NIXOS_LUSTRATE</literal>, skip ahead.</para></note>
+
+            <para>Prepare your target partition:</para>
+
+            <para>At this point it is time to prepare your target partition.
+                Please refer to the partitioning, file-system creation, and
+                mounting steps of <xref linkend="sec-installation" /></para>
+
+            <para>If you're about to install NixOS in place using
+                <literal>NIXOS_LUSTRATE</literal> there is nothing to do for
+                this step.</para>
+        </listitem>
+
+        <listitem>
+            <para>Generate your NixOS configuration:</para>
+
+            <screen>$ sudo `which nixos-generate-config` --root /mnt</screen>
+
+            <para>You'll probably want to edit the configuration files. Refer
+                to the <literal>nixos-generate-config</literal> step in <xref
+                    linkend="sec-installation" /> for more information.</para>
+
+            <para>Consider setting up the NixOS bootloader to give you the
+                ability to boot on your existing Linux partition. For instance,
+                if you're using GRUB and your existing distribution is running
+                Ubuntu, you may want to add something like this to your
+                <literal>configuration.nix</literal>:</para>
+
+            <programlisting>
+boot.loader.grub.extraEntries = ''
+  menuentry "Ubuntu" {
+    search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
+    configfile "($ubuntu)/boot/grub/grub.cfg"
+  }
+'';</programlisting>
+
+            <para>(You can find the appropriate UUID for your partition in
+                <literal>/dev/disk/by-uuid</literal>)</para>
+        </listitem>
+
+        <listitem>
+            <para>Create the <literal>nixbld</literal> group and user on your
+                original distribution:</para>
+
+            <screen>
+$ sudo groupadd -g 30000 nixbld
+$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen>
+        </listitem>
+
+        <listitem>
+            <para>Download/build/install NixOS:</para>
+
+            <warning><para>Once you complete this step, you might no longer be
+                    able to boot on existing systems without the help of a
+                    rescue USB drive or similar.</para></warning>
+
+            <screen>$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen>
+
+            <para>Again, please refer to the <literal>nixos-install</literal>
+                step in <xref linkend="sec-installation" /> for more
+                information.</para>
+
+            <para>That should be it for installation to another partition!</para>
+        </listitem>
+
+        <listitem>
+            <para>Optionally, you may want to clean up your non-NixOS distribution:</para>
+
+            <screen>
+$ sudo userdel nixbld
+$ sudo groupdel nixbld</screen>
+
+            <para>If you do not wish to keep the Nix package mananager
+                installed either, run something like <literal>sudo rm -rv
+                    ~/.nix-* /nix</literal> and remove the line that the Nix
+                installer added to your <literal>~/.profile</literal>.</para>
+        </listitem>
+
+        <listitem>
+            <note><para>The following steps are only for installing NixOS in
+                    place using
+                    <literal>NIXOS_LUSTRATE</literal>:</para></note>
+
+            <para>Generate your NixOS configuration:</para>
+
+            <screen>$ sudo `which nixos-generate-config` --root /</screen>
+
+            <para>Note that this will place the generated configuration files
+                in <literal>/etc/nixos</literal>. You'll probably want to edit
+                the configuration files. Refer to the
+                <literal>nixos-generate-config</literal> step in <xref
+                    linkend="sec-installation" /> for more information.</para>
+
+            <para>You'll likely want to set a root password for your first boot
+                using the configuration files because you won't have a chance
+                to enter a password until after you reboot. You can initalize
+                the root password to an empty one with this line: (and of course
+                don't forget to set one once you've rebooted or to lock the
+                account with <literal>sudo passwd -l root</literal> if you use
+                <literal>sudo</literal>)</para>
+
+            <programlisting>users.extraUsers.root.initialHashedPassword = "";</programlisting>
+        </listitem>
+
+        <listitem>
+            <para>Build the NixOS closure and install it in the
+                <literal>system</literal> profile:</para>
+
+            <screen>$ nix-env -p /nix/var/nix/profiles/system -f '&lt;nixpkgs/nixos&gt;' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen>
+        </listitem>
+
+        <listitem>
+            <para>Change ownership of the <literal>/nix</literal> tree to root
+                (since your Nix install was probably single user):</para>
+
+            <screen>$ sudo chown -R 0.0 /nix</screen>
+        </listitem>
+
+        <listitem>
+            <para>Set up the <literal>/etc/NIXOS</literal> and
+                <literal>/etc/NIXOS_LUSTRATE</literal> files:</para>
+
+            <para><literal>/etc/NIXOS</literal> officializes that this is now a
+                NixOS partition (the bootup scripts require its presence).</para>
+
+            <para><literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup
+                scripts to move <emphasis>everything</emphasis> that's in the
+                root partition to <literal>/old-root</literal>. This will move
+                your existing distribution out of the way in the very early
+                stages of the NixOS bootup. There are exceptions (we do need to
+                keep NixOS there after all), so the NixOS lustrate process will
+                not touch:</para>
+
+            <itemizedlist>
+                <listitem><para>The <literal>/nix</literal>
+                        directory</para></listitem>
+
+                <listitem><para>The <literal>/boot</literal>
+                        directory</para></listitem>
+
+                <listitem><para>Any file or directory listed in
+                        <literal>/etc/NIXOS_LUSTRATE</literal> (one per
+                        line)</para></listitem>
+            </itemizedlist>
+
+            <para>Let's create the files:</para>
+
+            <screen>
+$ sudo touch /etc/NIXOS
+$ sudo touch /etc/NIXOS_LUSTRATE</screen>
+
+            <para>Let's also make sure the NixOS configuration files are kept
+                once we reboot on NixOS:</para>
+
+            <screen>
+$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE</screen>
+        </listitem>
+
+        <listitem>
+            <para>Finally, move the <literal>/boot</literal> directory of your
+                current distribution out of the way (the lustrate process will
+                take care of the rest once you reboot, but this one must be
+                moved out now because NixOS needs to install its own boot
+                files:</para>
+
+            <warning><para>Once you complete this step, your current
+                    distribution will no longer be bootable! If you didn't get
+                    all the NixOS configuration right, especially those
+                    settings pertaining to boot loading and root partition,
+                    NixOS may not be bootable either. Have a USB rescue device
+                    ready in case this happens. </para></warning>
+
+            <screen>
+$ sudo mv -v /boot /boot.bak &amp;&amp;
+    sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot</screen>
+
+            <para>Cross your fingers, reboot, hopefully you should get a NixOS
+                prompt!</para>
+        </listitem>
+        <listitem>
+            <para>If for some reason you want to revert to the old
+                distribution, you'll need to boot on a USB rescue disk and do
+                something along these lines:</para>
+
+            <screen>
+# mkdir root
+# mount /dev/sdaX root
+# mkdir root/nixos-root
+# mv -v root/* root/nixos-root/
+# mv -v root/nixos-root/old-root/* root/
+# mv -v root/boot.bak root/boot  # We had renamed this by hand earlier
+# umount root
+# reboot</screen>
+
+            <para>This may work as is or you might also need to reinstall the
+                boot loader</para>
+
+            <para>And of course, if you're happy with NixOS and no longer need
+                the old distribution:</para>
+
+            <screen>sudo rm -rf /old-root</screen>
+        </listitem>
+
+        <listitem>
+            <para>It's also worth noting that this whole process can be
+                automated. This is especially useful for Cloud VMs, where
+                provider do not provide NixOS. For instance, <link
+                    xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link>
+                uses the lustrate process to convert Digital Ocean droplets to
+                NixOS from other distributions automatically.</para>
+        </listitem>
+    </orderedlist>
+</section>
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml
index 2a5d1fc3ce8d..e20b6574b725 100644
--- a/nixos/doc/manual/installation/installing.xml
+++ b/nixos/doc/manual/installation/installing.xml
@@ -401,5 +401,6 @@ drive (here <filename>/dev/sda</filename>).  <xref linkend="ex-config"
 <xi:include href="installing-usb.xml" />
 <xi:include href="installing-pxe.xml" />
 <xi:include href="installing-virtualbox-guest.xml" />
+<xi:include href="installing-from-other-distro.xml" />
 
 </chapter>