content/wiki/install/install.md

This guide for installing MatterLinux 24 assumes you are in a live USB/CD/DVD environment. If you are not, then 
see the [introduction page](/wiki/intro).

# Loading keys for the ISO
If you are using the MatterLinux ISO for the installation, you should load your key map to make  
it easier to work in the TTY. All the available key maps can be listed with:
```
# localectl list-keymaps
```
To load a key map, you can use the `loadkeys` command, for example:
```
# loadkeys tr_q-latin5
```

# Setting up the Installation Disk  
During the installation, the installation disk will be referred as `$DISK`. In order to 
copy paste commands easily, you can set this as an environment variable:
```
# export DISK=/dev/sda
```
If you are not sure which disk is your installation disk, you can use the `lsblk` command. 

**Please note that the installation will wipe your entire drive, so backup any important data you may have.**

### Creating partitions
You can use the `fdisk` tool to format your disk:
```
# fdisk $DISK
```
Here are the simple commands in `fdisk`:
- `d`: Delete the last partition
- `n`: Create a new partition
- `w`: Save the changes

If you have old partitions left on the disk, clean them with the `d` command. 

For this guide we will be using two separate partitions for `/boot` and `/`. So after removing 
old partitions create 2 new partitions with the `n` command:

- For the first partition hit enter till you see the `Last Sector` input. Here type `+1G`. You can 
make your `/boot` partition larger or smaller if you wish.
- For the second partition, just hit enter for all the inputs to use the rest of the disk.

When you are done save the changes with `w`.

### Formatting the partitions 
Now you should have 2 new partitions. You can confirm this using the `lsblk` command:
```
# lsblk $DISK
```
We will refer these partitions as `$BOOT` and `$ROOT`:
```
# export BOOT=${DISK}1
# export ROOT=${DISK}2
```

We will be formatting `$BOOT` and `$ROOT` with EXT4. You can really use any file system. 

> **Important**
>
> You should use FAT32 for `$BOOT` if you are doing an UEFI installation.

To format the partitions as described above:
```
# mkfs.ext4 $BOOT
# mkfs.ext4 $ROOT
```

### Mounting 
Mount the `$ROOT` partition to `/mnt`, and the `$BOOT` partition to `/mnt/boot`:
```
# mount $ROOT /mnt
# mount --mkdir $BOOT /mnt/boot
```

# Installing the base system 
[Download and verify the latest release archive](/download). This can be done using the 
`curl` and the `gpg` tool.

After downloading and verifying the archive extract it to the `/mnt` directory:
```
# tar xvf <archive name> -C /mnt
```

### Package Manager Configuration
Copy over the `mp` configuration to the new system:
```
# cp /etc/mp/cfg /mnt/etc/mp/cfg
```

### Change Root
To change root (`chroot`) into the new system, you can use the `matter-chroot` tool, which is a part of [MatterLinux `tools`
project](https://git.matterlinux.xyz/Matter/tools): 
```
# matter-chroot /mnt 
```

### Setup Timezone
Link `/etc/localtime` to your localtime zone. Timezones are located under 
`/usr/share/zoneinfo`. For example:
```
# ln -sf /usr/share/zoneinfo/Europe/Istanbul /etc/localtime
```

### Setup Locales
List all the avaliable locales with `locale -a`, then place the locale you want into the 
`/etc/locale.gen` file with the following format:
```
full_locale_name UTF-8
```
For example:
```
en_US.UTF-8 UTF-8
```
Then run the `locale-gen` command to generate all the locales. Lastly place the locale of your choice 
into the `/etc/locale.conf` file, for example:
```
# echo "LANG=en_US.UTF-8" > /etc/locale.conf
```


### Installing Important Packages 
After changing root, you can now start installing other base system packages that are not included in the release archive. 
But first thing first, sync all the packages and add the repo public keys:
```
# mp-sync
# gpg --receive-keys F9E70878C2FB389AEC2BA34CA3654DF5AD9F641D 
```

Now it is time to install packages. You should install `systemd` and `dhcpcd`:
```
# mp-install systemd dhcpcd
```
You should also run this `systemctl` command after installation:
```
# systemctl preset-all
```

### Host name and fstab 
Enter your host name into `/etc/hostname` using a text editor like `vim` or `nano`.
Then configure the `/etc/fstab`, again, using the text editor of your choice:
```
# device   | mount-point | file system | options    | dump  | fsck 
# ======== | =========== | =========== | ========== | ===== | =======
$ROOT        /             ext4          defaults     1       1
$BOOT        /boot         ext4          defaults     0       0
```
Change the configuration accordingly. 

### Changing the Root Password
Change your root password:
```
# passwd
```

### Installing the kernel
Install the linux kernel with `mp`:
```
# mp-install linux
```
Verify the installation:
```
# ls -la /boot/vmlinuz-linux
```

# Installing GRUB
For the grub BIOS installation, install the `grub-bios` package:
```
# mp-install grub-bios
```

> **Important** 
>
> For the grub UEFI installation, install the `grub-efi` package
> instead of `grub-bios`

### Installation and Configuration
To install grub to your boot partition, run:
```
# grub-install $DISK
```

To auto generate grub configuration, run:
```
# grub-mkconfig -o /boot/grub/grub.cfg
```

# Cleanup and Reboot 
Exit the `chroot` environment and `umount` all the disks:
```
# umount $BOOT
# umount $ROOT
```
Now reboot your system and boot from the installation disk. Login with as root with your password.
Congratulations, you have just installed MatterLinux!