NixOS Installation Guide/en: Difference between revisions

Line 1:

This guide is a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation official manual]. It describes installation of [[NixOS]] as a complete operating system. For ~~installation of~~ [[Nix]] within an existing operating system, ~~see~~ [[Nix Installation Guide]].

This guide serves as a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation official manual]. It describes installation of [[NixOS]] as a complete operating system. For instructions on installing [[Nix]] within an existing operating system, refer to the [[Nix Installation Guide]].

In addition to ~~describing~~ the steps from the official manual, it provides known good instructions for common use cases. When there is a discrepancy between the manual and this guide, the supported case is the one described in the manual.

In addition to covering the steps from the official manual, it provides known good instructions for common use cases. When there is a discrepancy between the manual and this guide, the supported case is the one described in the manual.

~~Use this guide as a step-by-step guide, choices will be presented, use only the selected section, and continue at the section it tells you to at the end~~.

== Installation target ==

Line 67:

Line 66:

~~Since the~~ installation media is hybrid~~, it will boot~~ both in legacy ~~bios~~ mode and UEFI mode.

The installation media is hybrid and is capable of booting in both legacy BIOS mode and [[UEFI]] mode.

Whatever mode is used to boot the installation media, your motherboard or computer's configuration may need to be changed to allow booting from a Optical Disk Drive (for CD/DVD) or an external USB drive.

Line 93:

Line 92:

=== Wireless ===

~~Network Manager~~ is installed on the graphical ISO, meaning that it is possible to use <code>nmtui</code> on the command line to connect to a network.

[[NetworkManager]] is installed on the graphical ISO, meaning that it is possible to use <code>nmtui</code> on the command line to connect to a network.

Using the "Applications" tab at top

left or the launcher bar at bottom, choose a terminal application and from there launch <code>nmtui</code>. This will allow you to 'activate' a (wireless) connection - your local SSIDs should be visible in the list, else you can add a new connection. When the wireless connection is active and you have tested it, it is likely the install app which launched on startup has not detected the new connection. Close down the install app, and reopen it from the launcher bar at the bottom of the screen. This should then find the new connection and proceed.

On the minimal ISO, or if you are more familiar with ~~<code>~~wpa_supplicant~~</code>~~ then you can also run <code>wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf</code>, then enter your password and <code>systemctl restart wpa_supplicant</code>.

On the minimal ISO, or if you are more familiar with [[wpa_supplicant]] then you can also run <code>wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf</code>, then enter your password and <code>systemctl restart wpa_supplicant</code>.

== Partitioning ==

To partition the persistent storage run <code>sudo fdisk /dev/diskX</code> and follow instructions for ~~DOS~~ or (U)EFI.

To partition the persistent storage run <code>sudo fdisk /dev/diskX</code> and follow instructions for MBR or (U)EFI. To determine which mode you are booted into, run:

$ [ -d /sys/firmware/efi/efivars ] && echo "UEFI" || echo "Legacy"

</syntaxhighlight>

A very simple example setup is given here.

=== ~~DOS~~ ===

=== Legacy Boot (MBR) ===

* o (dos disk label)

Line 136:

Line 140:

* w (write)

== ~~Label~~ partitions ==

=== Format partitions ===

The example below uses the [[ext4]] filesystem format. If you wish to use other filesystem formats such as [[Btrfs]] or [[ZFS]]:

* [[Bcachefs#NixOS installation on bcachefs]]

* [[Btrfs#Installation of NixOS on btrfs]]

* [[LVM#Basic Setup]]

* [[ZFS#Simple NixOS ZFS on root installation]]

This is useful for having multiple setups and makes partitions easier to handle<syntaxhighlight lang="console">

This is useful for having multiple setups and makes partitions easier to handle

$ lsblk

~~$ sudo~~ mkfs.fat -F 32 /dev/sdX1

~~$ sudo fatlabel /dev/sdX1 NIXBOOT~~

$ lsblk # lists current system block devices

~~$ sudo~~ mkfs.ext4 /dev/sdX2 -L ~~NIXROOT~~

# mkfs.fat -F 32 -n boot /dev/sdX1

~~$ sudo~~ mount /dev/disk/by-label/~~NIXROOT~~ /mnt

# mkfs.ext4 /dev/sdX2 -L nixos

~~$ sudo~~ mkdir -p /mnt/boot

# mount /dev/disk/by-label/nixos /mnt

~~$ sudo~~ mount /dev/disk/by-label/~~NIXBOOT~~ /mnt/boot

# mkdir -p /mnt/boot

# mount /dev/disk/by-label/boot /mnt/boot

</syntaxhighlight>

== ~~Swap file~~ ==

== NixOS configuration ==

NixOS is configured through a [[Overview of the NixOS Linux distribution#Declarative Configuration|declarative configuration]] file. To generate a default config file, run [[nixos-generate-config]]:

~~$ sudo dd if=/dev/zero of=/mnt/.swapfile bs=1024 count=2097152 (2GB size)~~

# nixos-generate-config --root /mnt

~~$ sudo chmod 600~~ /mnt~~/.swapfile~~

# nano /mnt/etc/nixos/configuration.nix

~~$ sudo mkswap~~ /mnt/~~.swapfile~~

~~$ sudo swapon~~ /~~mnt~~/.~~swapfile~~

</syntaxhighlight>

== NixOS ~~config ==~~

For information on working with a system configuration, see [[NixOS system configuration]]. For desktop-specific configurations, see [[NixOS as a desktop]].

~~<syntaxhighlight lang="console">~~

~~$ sudo nixos~~-~~generate-config --root /mnt~~

Most essential changes:

~~$ cd /mnt/etc/nixos/~~

~~$ sudo vim configuration.nix~~

~~</syntaxhighlight>~~Most essential changes:

* keyboard layout, ie <code>[[Keyboard Layout Customization|services.xserver.xkb.layout]]</code>

* <code>users.users.user</code> with adding entry <code>initialPassword = "pw123";</code>

* [[networking]] (wifi), see below for fix if it breaks

* <code>boot.loader.grub.device = "/dev/sda"; #or "nodev" for efi only</code>

* install [[:Category:Text Editor|editor]] to edit the configuration

* install editor to edit the configuration

* change hardware config to use labels

The self-documenting NixOS options can be searched with [https://search.nixos.org/options NixOS options search].

=== Swap file ===

For additional methods of configuring swap, see [[Swap]]. The following example demonstrates how to create and enable a [[Swap#Swap file|swap file]]:

{{file|/mnt/etc/nixos/configuration.nix|nix|

swapDevices = [{

device = "/var/lib/swapfile";

size = 16*1024; # 16 GB

}];

</nowiki>

}}

=== Bootloader ===

NixOS supports multiple [[Bootloader|bootloaders]] such as [[GNU GRUB]] and [[Systemd/boot]].

Systemd-boot is the recommended bootloader. The following example demonstrates how to enable systemd-boot in your configuration:

{{file|/mnt/etc/nixos/configuration.nix|nix|

boot.loader.systemd-boot.enable = true;

</nowiki>

}}

You may also wish to configure [[Secure Boot]].

=== Users ===

For information on creating and managing users, see [[User management]] and the {{NixOS Manual|name=NixOS Manual: Chapter - Package Management|anchor=#sec-user-management}}. See an example below:

{{file|/mnt/etc/nixos/configuration.nix|nix|

users.users.alice = {

isNormalUser = true;

initialPassword = "pw123";

};

</nowiki>

}}

== NixOS installation ==

$ cd /mnt

# cd /mnt

~~$ sudo~~ nixos-install

# nixos-install

</syntaxhighlight>~~after installation: Run <code>passwd</code> to change user password.~~

</syntaxhighlight>

if internet broke/breaks, try one of the following:<syntaxhighlight lang="console">

after installation: Run <code>passwd</code> to change user password.

$ nixos-rebuild switch --option substitute false # no downloads

$ nixos-rebuild switch --option binary-caches "" # no downloads

if internet broke/breaks, try one of the following:

# nixos-rebuild switch --option substitute false # no downloads

# nixos-rebuild switch --option binary-caches "" # no downloads

</syntaxhighlight>

* wpa_supplicant flags to connect to wifi

Line 193:

Line 246:

* Brand servers may require extra kernel modules be included into initrd (<code>boot.initrd.extraKernelModules</code> in configuration.nix) For example HP Proliant needs "hpsa" module to see the disk drive.

[[Category:Guide]][[Category:Deployment]]

[[Category:Guide]]

[[Category:Deployment]]

[[Category:NixOS]]

@@ Line 1: / Line 1: @@
-This guide is a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation official manual]. It describes installation of [[NixOS]] as a complete operating system. For installation of [[Nix]] within an existing operating system, see [[Nix Installation Guide]].
+<languages/>
+This guide serves as a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation official manual]. It describes installation of [[NixOS]] as a complete operating system. For instructions on installing [[Nix]] within an existing operating system, refer to the [[Nix Installation Guide]].
-In addition to describing the steps from the official manual, it provides known good instructions for common use cases. When there is a discrepancy between the manual and this guide, the supported case is the one described in the manual.
+In addition to covering the steps from the official manual, it provides known good instructions for common use cases. When there is a discrepancy between the manual and this guide, the supported case is the one described in the manual.
-Use this guide as a step-by-step guide, choices will be presented, use only the selected section, and continue at the section it tells you to at the end.
 == Installation target ==
@@ Line 67: / Line 66: @@
 {{expansion|Troubleshooting steps, and details are lacking.}}
-Since the installation media is hybrid, it will boot both in legacy bios mode and UEFI mode.
+The installation media is hybrid and is capable of booting in both legacy BIOS mode and [[UEFI]] mode.
 Whatever mode is used to boot the installation media, your motherboard or computer's configuration may need to be changed to allow booting from a Optical Disk Drive (for CD/DVD) or an external USB drive.
@@ Line 93: / Line 92: @@
 === Wireless ===
-Network Manager is installed on the graphical ISO, meaning that it is possible to use <code>nmtui</code> on the command line to connect to a network.
+[[NetworkManager]] is installed on the graphical ISO, meaning that it is possible to use <code>nmtui</code> on the command line to connect to a network.
 Using the "Applications" tab at top
 left or the launcher bar at bottom, choose a terminal application and from there launch <code>nmtui</code>. This will allow you to 'activate' a (wireless) connection - your local SSIDs should be visible in the list, else you can add a new connection.  When the wireless connection is active and you have tested it, it is likely the install app which launched on startup has not detected the new connection.  Close down the install app, and reopen it from the launcher bar at the bottom of the screen.  This should then find the new connection and proceed.
-On the minimal ISO, or if you are more familiar with <code>wpa_supplicant</code> then you can also run <code>wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf</code>, then enter your password and <code>systemctl restart wpa_supplicant</code>.
+On the minimal ISO, or if you are more familiar with [[wpa_supplicant]] then you can also run <code>wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf</code>, then enter your password and <code>systemctl restart wpa_supplicant</code>.
 == Partitioning ==
-To partition the persistent storage run <code>sudo fdisk /dev/diskX</code> and follow instructions for DOS or (U)EFI.
+To partition the persistent storage run <code>sudo fdisk /dev/diskX</code> and follow instructions for MBR or (U)EFI. To determine which mode you are booted into, run:
+<syntaxhighlight lang="console">
+$ [ -d /sys/firmware/efi/efivars ] && echo "UEFI" || echo "Legacy"
+</syntaxhighlight>
 A very simple example setup is given here.
-=== DOS ===
+=== Legacy Boot (MBR) ===
 * o (dos disk label)
@@ Line 136: / Line 140: @@
 * w (write)
-== Label partitions ==
+=== Format partitions ===
+The example below uses the [[ext4]] filesystem format. If you wish to use other filesystem formats such as [[Btrfs]] or [[ZFS]]:
+* [[Bcachefs#NixOS installation on bcachefs]]
+* [[Btrfs#Installation of NixOS on btrfs]]
+* [[LVM#Basic Setup]]
+* [[ZFS#Simple NixOS ZFS on root installation]]
-This is useful for having multiple setups and makes partitions easier to handle<syntaxhighlight lang="console">
+This is useful for having multiple setups and makes partitions easier to handle
-$ lsblk
-$ sudo mkfs.fat -F 32 /dev/sdX1
+<syntaxhighlight lang="console">
-$ sudo fatlabel /dev/sdX1 NIXBOOT
+$ lsblk # lists current system block devices
-$ sudo mkfs.ext4 /dev/sdX2 -L NIXROOT
+# mkfs.fat -F 32 -n boot /dev/sdX1
-$ sudo mount /dev/disk/by-label/NIXROOT /mnt
+# mkfs.ext4 /dev/sdX2 -L nixos
-$ sudo mkdir -p /mnt/boot
+# mount /dev/disk/by-label/nixos /mnt
-$ sudo mount /dev/disk/by-label/NIXBOOT /mnt/boot
+# mkdir -p /mnt/boot
+# mount /dev/disk/by-label/boot /mnt/boot
 </syntaxhighlight>
-== Swap file ==
+== NixOS configuration ==
+NixOS is configured through a [[Overview of the NixOS Linux distribution#Declarative Configuration|declarative configuration]] file. To generate a default config file, run [[nixos-generate-config]]:
 <syntaxhighlight lang="console">
-$ sudo dd if=/dev/zero of=/mnt/.swapfile bs=1024 count=2097152 (2GB size)
+# nixos-generate-config --root /mnt
-$ sudo chmod 600 /mnt/.swapfile
+# nano /mnt/etc/nixos/configuration.nix
-$ sudo mkswap /mnt/.swapfile
-$ sudo swapon /mnt/.swapfile
 </syntaxhighlight>
-== NixOS config ==
+For information on working with a system configuration, see [[NixOS system configuration]]. For desktop-specific configurations, see [[NixOS as a desktop]].
-<syntaxhighlight lang="console">
-$ sudo nixos-generate-config --root /mnt
+Most essential changes:
-$ cd /mnt/etc/nixos/
-$ sudo vim configuration.nix
-</syntaxhighlight>Most essential changes:
 * keyboard layout, ie <code>[[Keyboard Layout Customization|services.xserver.xkb.layout]]</code>
-* <code>users.users.user</code> with adding entry <code>initialPassword = "pw123";</code>
 * [[networking]] (wifi), see below for fix if it breaks
-* <code>boot.loader.grub.device = "/dev/sda"; #or "nodev" for efi only</code>
+* install [[:Category:Text Editor|editor]] to edit the configuration
-* install editor to edit the configuration
-* change hardware config to use labels
 The self-documenting NixOS options can be searched with [https://search.nixos.org/options NixOS options search].
+=== Swap file ===
+For additional methods of configuring swap, see [[Swap]]. The following example demonstrates how to create and enable a [[Swap#Swap file|swap file]]:
+{{file|/mnt/etc/nixos/configuration.nix|nix|
+<nowiki>
+  swapDevices = [{
+    device = "/var/lib/swapfile";
+    size = 16*1024; # 16 GB
+  }];
+</nowiki>
+}}
+=== Bootloader ===
+NixOS supports multiple [[Bootloader|bootloaders]] such as [[GNU GRUB]] and [[Systemd/boot]].
+Systemd-boot is the recommended bootloader. The following example demonstrates how to enable systemd-boot in your configuration:
+{{file|/mnt/etc/nixos/configuration.nix|nix|
+<nowiki>
+  boot.loader.systemd-boot.enable = true;
+</nowiki>
+}}
+You may also wish to configure [[Secure Boot]].
+=== Users ===
+For information on creating and managing users, see [[User management]] and the {{NixOS Manual|name=NixOS Manual: Chapter - Package Management|anchor=#sec-user-management}}. See an example below:
+{{file|/mnt/etc/nixos/configuration.nix|nix|
+<nowiki>
+  users.users.alice = {
+    isNormalUser = true;
+    initialPassword = "pw123";
+  };
+</nowiki>
+}}
 == NixOS installation ==
 <syntaxhighlight lang="console">
-$ cd /mnt
+# cd /mnt
-$ sudo nixos-install
+# nixos-install
-</syntaxhighlight>after installation: Run <code>passwd</code> to change user password.
+</syntaxhighlight>
-if internet broke/breaks, try one of the following:<syntaxhighlight lang="console">
+after installation: Run <code>passwd</code> to change user password.
-$ nixos-rebuild switch --option substitute false # no downloads
-$ nixos-rebuild switch --option binary-caches "" # no downloads
+if internet broke/breaks, try one of the following:
+<syntaxhighlight lang="console">
+# nixos-rebuild switch --option substitute false # no downloads
+# nixos-rebuild switch --option binary-caches "" # no downloads
 </syntaxhighlight>
 * wpa_supplicant flags to connect to wifi
@@ Line 193: / Line 246: @@
 * Brand servers may require extra kernel modules be included into initrd (<code>boot.initrd.extraKernelModules</code> in configuration.nix) For example HP Proliant needs "hpsa" module to see the disk drive.
-[[Category:Guide]][[Category:Deployment]]
+[[Category:Guide]]
+[[Category:Deployment]]
+[[Category:NixOS]]