path: root/docs/01-install.md

Install Alice
=============

Here is a guide to installing Alice Linux on your computer using the chroot method. You can do this from your existing Linux distribution or from a live environment, such as Alice Live or another Linux distribution. Make sure your chosen environment has the necessary partitioning tools, filesystem tools, and extraction tools.

Get Alice rootfs tarball
------------------------

Download the Alice rootfs tarball from the [download](https://alicelinux.org/download.html) page, along with its `sha256sum` file.
```
$ curl -O <url>
$ curl -O <url>.sha256sum
```

Verify the checksum of the Alice rootfs tarball.
```
$ sha256sum -c alicelinux-rootfs-20240525.tar.xz.sha256sum
alicelinux-rootfs-20240525.tar.xz: OK
```

Prepare the partition and filesystem
------------------------------------

Prepare the partition and filesystem of your choice. In this guide, I will use `ext4` as an example.
```
# cfdisk /dev/sdX
# mkfs.ext4 /dev/sdXY
```

Mount your created partition somewhere. In this guide, I will use `/mnt/alice` as the mount point.
```
# mkdir /mnt/alice
# mount /dev/sdXY /mnt/alice
```

Extract the Alice rootfs tarball
--------------------------------

Extract the Alice rootfs into the mounted partition.
```
$ tar xvf alicelinux-rootfs-*.tar.xz -C /mnt/alice
```

Enter chroot
------------

First, chroot into Alice. (Replace `/mnt/alice` with your chosen mount point)
```
# /mnt/alice/usr/bin/apkg-chroot /mnt/alice
```

Any further commands after this will be executed inside the Alice environment. 

Configure apkg
---------------

Once we have the repositories cloned, we need to configure `apkg`. `apkg` is Alice's package build system (or package manager). `apkg` configuration is environment-based -- settings are exported as environment variables. Place them in `/etc/profile.d/apkg.sh` for system-wide configuration, or in `~/.profile` for per-user configuration.

First, we set `CFLAGS` and `CXXFLAGS`. Alice base packages are built using `-O3 -march=x86-64 -pipe`. You can use these settings or change them to your preference.
```
# export CFLAGS="-O3 -march=x86-64 -pipe"
```

And use whats in `CFLAGS` for `CXXFLAGS`.
```
# export CXXFLAGS="$CFLAGS"
```

Next set `MAKEFLAGS`. I will use `6` for my `8 threads` machine.
```
# export MAKEFLAGS="-j6"
```

Next, we need to set the package's build scripts path (I'll call it `package repos`) so `apkg` can find them. The `APKG_REPO` variable can accept multiple values for multiple `package repos`.

Alice provides two (2) `package repos` (at the time of this writing): `core` and `extra`. `core` contains all base packages, and `extra` includes other packages beyond the base.

I'm gonna use directory `/var/lib/repos/core` and `/var/lib/repos/extra` for `core` and `extra` repos respectively.
```
# export APKG_REPO="/var/lib/repos/core /var/lib/repos/extra"
```

You can also add `community` repo too.
> NOTE: The `community` repo is not held to the same standards as the official repos.
> Additionally all repo paths must be declared in the APKG_REPO variable, separated by a single space.
```
# export APKG_REPO="/var/lib/repos/core /var/lib/repos/extra /var/lib/repos/community"
```

Next, we will set up directories for `packages`, `sources`, and `work`. By default, these directories are inside the package port, but we will change them to `/var/cache/pkg`, `/var/cache/src`, and `/var/cache/work` respectively. You can change these to any location where you want to store these files.

First, create the directories.
```
# mkdir -p /var/cache/pkg
# mkdir -p /var/cache/src
# mkdir -p /var/cache/work
```

export These configuration environment
```
# export APKG_PACKAGE_DIR=/var/cache/pkg
# export APKG_SOURCE_DIR=/var/cache/src
# export APKG_WORK_DIR=/var/cache/work
```

Configure reposync
--------------------

`reposync` is a tool to sync package ports from git repositories. Like `apkg`, `reposync` configuration is environment-based. Add remote repos for `core` and `extra` to `/etc/profile.d/reposync.sh` (system-wide) or `~/.profile` (per-user). The format is `<gitrepo>|<branch>|<localpath>`.
```
# export REPOSYNC_CORE="https://codeberg.org/emmett1/alicelinux|core|/var/lib/repos/core"
# export REPOSYNC_EXTRA="https://codeberg.org/emmett1/alicelinux|extra|/var/lib/repos/extra"
```

If you also want the `community` repo, add it as well.
> NOTE: The `community` repo is not held to the same standards as the official repos.
```
# export REPOSYNC_COMMUNITY="https://codeberg.org/emmett1/alicelinux|community|/var/lib/repos/community"
```


Now run `reposync` to sync latest ports.
```
# reposync
```
 
After setting up our `package repos`, make sure `apkg` can find the packages. We can use `apkg -s <pattern>` to search for packages.
```
# apkg -s sway
swayidle
swaybg
swaylock
sway
```

Lets combine with `-p` flags to show path or package port.
```
# apkg -p $(apkg -s sway)
/var/lib/repos/extra/sway
/var/lib/repos/extra/swaylock
/var/lib/repos/extra/swaybg
/var/lib/repos/extra/swayidle
```

If the output appears, then we are good to go.

Full system upgrade/rebuild
---------------------------

On the first install, we should upgrade the system first.

Before we do, install development packages first.
```
# apkg -I muon cmake pkgconf libtool automake perl python
```

> NOTE: use uppercase 'i' for solve dependencies, lowercase 'i' without solve dependencies.

Now lets upgrade our system.
```
# apkg -U
```

> NOTE: Use uppercase `U` for a system upgrade, and lowercase `u` to upgrade a specific package of your choice.

If you changed `CFLAGS` and `CXXFLAGS` to something other than the default, it's a good time to perform a full rebuild first. In this case, you can skip upgrading the system because performing a full rebuild will already use the latest version in `package repos`.
```
# apkg -u $(apkg -a)
```

> NOTE: Add the `-f` flag to force rebuild of existing prebuilt package.
> NOTE: `apkg -a` prints all installed packages on the system.

Install kernel
--------------

You can configure your own kernel from [kernel.org](https://kernel.org/) or use the one provided by Alice.

> NOTE: The provided kernel will take a lot of time to compile because many options are enabled.

If you want to use Alice's kernel, just run.
```
# apkg -I linux
```

Install firmware
----------------

If your hardware requires firmware, install it using.
```
# apkg -I linux-firmware
```

Hostname
--------

Change `alice` to the hostname of your choice.
```
# echo alice > /etc/hostname
```

Fstab
-----

Change the partition and filesystem of your choice below.
```
# echo '/dev/sda1 swap swap defaults 0 1' >> /etc/fstab
# echo '/dev/sda2 / ext4 defaults 0 0' >> /etc/fstab
```

Enable runit services
---------------------

Alice uses busybox's `runit` as its main service manager. Enable the required services.
```
# ln -s /etc/sv/tty1 /var/service
# ln -s /etc/sv/tty2 /var/service
# ln -s /etc/sv/tty3 /var/service
```

I'm enabling 3 `tty` services. `tty` is required; without it, you won't be able to log in (or run any commands).

> The runit service directory is `/etc/sv`.
> Create a symlink from `/etc/sv/<service>` to `/var/service` to enable it; remove the symlink to disable it.

Setup user and password
-----------------------

Add your user.
```
# adduser <user>
```

Add your user to the `wheel` group.
```
# adduser <user> wheel
```

You might need to add your user to the `input` and `video` groups to start the Wayland compositor later, and the `audio` group to have working audio.
```
# adduser <user> input
# adduser <user> video
# adduser <user> audio
```

Root password
-------------

Set the password for the `root` user.
```
# passwd
```

Timezone
--------

Install `tzdata`.
```
# apkg -I tzdata
```

Then create a symlink for your timezone to `/etc/localtime`.
```
# ln -s /usr/share/zoneinfo/Asia/Kuala_Lumpur /etc/localtime
```

Alternatively, you can copy it and then uninstall `tzdata` to keep your installed packages minimal.
```
# cp /usr/share/zoneinfo/Asia/Kuala_Lumpur /etc/localtime
# apkg -r tzdata
```

Install bootloader
------------------

See the [bootloader documentation](bootloader.html) for installing and configuring a bootloader.

Networking
----------

See the [networking documentation](networking.html) for setting up networking.

Reboot and enjoy!
-----------------

Exit the chroot environment and unmount the Alice partition, then reboot.
```
# exit
# umount /mnt/alice
# reboot
```

Some important notes
====================

- `Alice` uses `spm` and `apkg` as its package manager and package build system. Run with the `-h` flag to see available options.
- Additional scripts are provided with the name `apkg-<script>` which will be added (or removed) from time to time.
- Use `revdep` to scan for broken libraries and binaries after system upgrades and package removals. You can use `revdep -v` to print out missing required libraries, and use `apkg -f -u $(revdep)` to scan and rebuild broken packages.
- Run `updateconf` to update config files in `/etc` after package upgrades.