mirror of
https://github.com/nix-community/disko
synced 2024-11-10 06:14:14 +00:00
- Revamped Quickstart
- Added document index and added links to it to README etc - Created placeholders for System Requirements and Support Matrix docs
This commit is contained in:
Jill
lassulus
parent
bd18ca94bd
commit
a1d9321eb7
1 changed files with 56 additions and 61 deletions
|
|
@ -1,121 +1,116 @@
|
|||
# Disko quickstart
|
||||
# Quickstart: disko
|
||||
|
||||
This tutorial will guide you through the process of installing NixOS on a single
|
||||
disk system using Disko.
|
||||
This tutorial describes how to install NixOS on a single disk system using `disko`. You will also need to refer to the NixOS manual, which is available [here.](https://nixos.org/manual/nixos/stable/index.html#ex-config)
|
||||
|
||||
1. Booting the installer
|
||||
Please note that `disko` will reformat the entire disk and overwrite any existing partitions. Dual booting with other operating systems is not supported.
|
||||
|
||||
Download NixOS ISO images from the NixOS download page
|
||||
(https://nixos.org/download.html#nixos-iso) and create a bootable USB drive
|
||||
following the instructions in [Section 2.4.1 "Booting from a USB flash drive"](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb)
|
||||
of the NixOS manual.
|
||||
## Step 1: Choose a Disk Configuration
|
||||
|
||||
2. The disk name
|
||||
Configurations for the most common disk layouts are provided in the [examples directory](https://github.com/nix-community/disko/tree/master/example) of the `disko` repository. Decide which of these layouts best suits your requirements. If you're not sure which layout to pick, use the [hybrid](https://github.com/nix-community/disko/blob/master/example/hybrid.nix) configuration. This layout is compatible with both BIOS and EFI systems.
|
||||
|
||||
Identify the name of your system disk by using the lsblk command.
|
||||
Refer to the [reference manual](./reference) for more information about the sample layouts and how to build your own configuration.
|
||||
|
||||
Once you've chosen your layout, you'll need to make a note of the URL to the raw file. To do this, open the file in Github. Immediately below the list of contributors, you will see a button labelled 'RAW' near the right hand side. Click this. The URL of the raw file will appear in the search bar of your browser. It will look something like this:
|
||||
|
||||
```
|
||||
https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix
|
||||
```
|
||||
|
||||
## Step 2: Boot the installer
|
||||
|
||||
Download the NixOS ISO image from the NixOS [download page](https://nixos.org/download.html#nixos-iso), and create a bootable USB drive following the instructions in [Section 2.4.1 "Booting from a USB flash drive"](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb) of the NixOS manual. Boot the machine from this USB drive.
|
||||
|
||||
## Step 3: Retrieve the disk name
|
||||
|
||||
Identify the name of your system disk by using the ```lsblk``` command as follows:
|
||||
|
||||
```
|
||||
$ lsblk
|
||||
```
|
||||
|
||||
The output from this command will look something like this:
|
||||
|
||||
```
|
||||
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
|
||||
nvme0n1 259:0 0 1,8T 0 disk
|
||||
```
|
||||
|
||||
In this example, an empty NVME SSD with 2TB space is shown as "nvme0n1" disk.
|
||||
Please note that Disko will reformat the entire disk and overwrite any existing
|
||||
partitions. Dual booting with other operating systems is not supported.
|
||||
In this example, an empty NVME SSD with 2TB space is shown with the disk name "nvme0n1". Make a note of the disk name as you will need it later.
|
||||
|
||||
## Step 4: Copy the disk configuration to your machine
|
||||
|
||||
3. Disk layout
|
||||
In Step 1, you chose a disk layout configuration from the [examples directory](https://github.com/nix-community/disko/tree/master/example), and made a note of its URL.
|
||||
|
||||
Choose a disk layout from the [examples directory](https://github.com/nix-community/disko/tree/master/example)
|
||||
Your configuration needs to be saved on the new machine as /tmp/disko-config.nix. You can do this using the ```curl``` command to download from the url you noted above, using the `-o` option to save the file as disko-config.nix. Your commands would look like this if you had chosen the hybrid layout:
|
||||
|
||||
For those who are unsure of which layout to pick, use the hybrid configuration
|
||||
found at https://github.com/nix-community/disko/blob/master/example/hybrid.nix
|
||||
and save it as `/tmp/disko-config.nix`. This layout is compatible with both BIOS
|
||||
and EFI systems.
|
||||
```
|
||||
cd /tmp
|
||||
$ curl https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix -o disko-config.nix
|
||||
```
|
||||
|
||||
4. Formatting
|
||||
## Step 5: Run disko to partition, format and mount your disks
|
||||
|
||||
The following step will reformat your disk and mount it to `/mnt`. Replace `<disk-name>` with the name of your disk obtained in step 1.
|
||||
The following step will partition and format your disk, and mount it to `/mnt`. Replace `<disk-name>` with the name of your disk obtained in Step 1.
|
||||
|
||||
Please note: This will erase any existing data on your disk.
|
||||
|
||||
```
|
||||
$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/<disk-name>" ]'
|
||||
$ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix --arg disks '[ "/dev/<disk-name>" ]'
|
||||
```
|
||||
|
||||
For example, if the disk name is `nvme0n1`:
|
||||
For example, if the disk name is `nvme0n1`, the command would be:
|
||||
|
||||
```
|
||||
$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
|
||||
$ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
|
||||
```
|
||||
|
||||
|
||||
After executing the command, the file systems will be mounted. You can verify
|
||||
this by running the following command:
|
||||
After the command has run, your file system should have been formatted and mounted. You can verify this by running the following command:
|
||||
|
||||
```
|
||||
$ mount | grep /mnt
|
||||
```
|
||||
|
||||
The output should look like this if your disk name is `nvme0n1`.
|
||||
|
||||
```
|
||||
/dev/nvme0n1p1 on /mnt type ext4 (rw,relatime,stripe=2)
|
||||
/dev/nvme0n1p2 on /mnt/boot type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro)
|
||||
```
|
||||
|
||||
5. Rest of the NixOS installation:
|
||||
## Step 6: Complete the NixOS installation.
|
||||
|
||||
Generate and modify the NixOS configuration.
|
||||
Your disks have now been formatted and mounted, and you are ready to complete the NixOS installation as described in the [NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-installation) - see the section headed "**Installing**", Steps 3 onwards. However, you will need to include the partitioning and formatting configurations that you copied into `/tmp/disko-config.nix` in your configuration, rather than allowing NixOS to generate information about your file systems. When you are configuring the system as per Step 4 of the manual, you should:
|
||||
|
||||
You now need to create a file `/mnt/etc/nixos/configuration.nix` that specifies
|
||||
the intended configuration of the system. This is because NixOS has a
|
||||
declarative configuration model: you create or edit a description of the desired
|
||||
configuration of your system, and then NixOS takes care of making it happen. The
|
||||
syntax of the NixOS configuration file is described in
|
||||
[Chapter 6, Configuration Syntax](https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax),
|
||||
while a list of available configuration options appears in
|
||||
[Appendix A, Configuration Options](https://nixos.org/manual/nixos/stable/options.html).
|
||||
A minimal example is shown in
|
||||
[Example: NixOS Configuration](https://nixos.org/manual/nixos/stable/index.html#ex-config).
|
||||
|
||||
The command nixos-generate-config can generate an initial configuration file for
|
||||
you.
|
||||
a) Include the `no-filesystems` switch when using the `nixos-generate-config` command to generate an initial `configuration.nix`. You will be supplying the file system configuration details from `disko-config.nix`. Your CLI command to generate the configuration will be:
|
||||
|
||||
```
|
||||
$ nixos-generate-config --no-filesystems --root /mnt
|
||||
```
|
||||
|
||||
We will include `--no-filesystems` the flag here so it won't add any filesystem
|
||||
mountpoints to the generated `/mnt/etc/nixos/hardware-configuration.nix` since
|
||||
we will re-use our disko configuration for that.
|
||||
This will create the file `configuration.nix` in `/mnt/etc/nixos`.
|
||||
|
||||
Next move the disko configuration as well to /etc/nixos
|
||||
b) Move the `disko` configuration to /etc/nixos
|
||||
|
||||
```
|
||||
$ mv /tmp/disko-config.nix /mnt/etc/nixos
|
||||
```
|
||||
|
||||
You should then edit /mnt/etc/nixos/configuration.nix to suit your needs
|
||||
c) You can now edit `configuration.nix` as per your requirements. This is described in Step 4 of the manual. For more information about configuring your system, refer to the NixOS manual. [Chapter 6, Configuration Syntax](https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax) describes the NixOS configuration syntax, and [Appendix A, Configuration Options](https://nixos.org/manual/nixos/stable/options.html) gives a list of available options. You can find also find a minimal example of a NixOS configuration in the manual: [Example: NixOS Configuration](https://nixos.org/manual/nixos/stable/index.html#ex-config).
|
||||
|
||||
```
|
||||
$ nano /mnt/etc/nixos/configuration.nix
|
||||
```
|
||||
|
||||
While being in this file also add the disko nixos module as well as the
|
||||
disko-config.nix in the imports section of your generated configuration:
|
||||
d) When editing `configuration.nix`, you will need to add the `disko` NixOS module and `disko-config.nix` to the imports section. This section will already include the file `./hardware-configuration.nix`, and you can add the new entries just below this. This section will now include:
|
||||
|
||||
```
|
||||
imports =
|
||||
[ # Include the results of the hardware scan.
|
||||
./hardware-configuration.nix
|
||||
"${builtins.fetchTarball "https://github.com/nix-community/disko/archive/master.tar.gz"}/module.nix"
|
||||
(import ./disko-config.nix {
|
||||
disks = [ "/dev/<disk-name>" ]; # replace this with your disk name i.e. /dev/nvme0n1
|
||||
})
|
||||
];
|
||||
disko.devices = pkgs.callPackage ./disko-config.nix {
|
||||
disks = [ "/dev/<disk-name>" ]; # replace this with your disk name i.e. /dev/nvme0n1
|
||||
};
|
||||
```
|
||||
|
||||
If you went for the hybrid-partition scheme, then choose grub as a bootloader.
|
||||
Otherwise consult the NixOS manual. The following configuration for Grub works
|
||||
both EFI and BIOS systems. Add it to your configuration.nix while commenting out
|
||||
the existing lines about `systemd-boot`:
|
||||
e) If you chose the hybrid-partition scheme, then choose `grub` as a bootloader, otherwise follow the recommendations in Step 4 of the **Installation** section of the NixOS manual. The following configuration for `grub` works for both EFI and BIOS systems. Add this to your configuration.nix, commenting out the existing lines that configure `systemd-boot`. The entries will look like this:
|
||||
|
||||
```
|
||||
# ...
|
||||
|
|
@ -130,7 +125,7 @@ the existing lines about `systemd-boot`:
|
|||
# ...
|
||||
```
|
||||
|
||||
Then finish the installation and reboot your machine
|
||||
f) Finish the installation and reboot your machine,
|
||||
|
||||
```
|
||||
$ nixos-install
|
||||
|
|
|
|||
Loading…
Reference in a new issue