Skip to content

Guide (Master)

Jump to bottom
Fulgurance edited this page Dec 21, 2025 · 146 revisions

Welcome to the ISM Guide!

This new wiki is actually experimental, and because it focus on master branch at the moment, you will probably encounter issues.

1 - Introduction

This is the very last guide of ISM usage.

This documentation focus on the master branch version and help actually the tester to setup a good environment to test the last software features.

2 - Setup

All tests are performed under a virtual machine with VirtualBox and by using the Kubuntu LiveCD.

First start a new virtual machine from the Kubuntu LiveCD:

Minimal hardware requirements (for the virtual machine).:

  • 100GiB of storage
  • 16GiB of RAM

BEFORE THE NEXT STEP, FORMAT AND MOUNT THE PARTITION YOU NEED IN /mnt/ism

Apart of the /boot/efi directory, all files and directories in /mnt/ism should be owned by the current user, not root.

Then install all required tools to build the crosstool chain on the host system (Kubuntu). Just run:

sudo apt install gawk gcc g++ crystal texinfo autoconf automake bison meson patch git

Create the required group and user for ISM:

sudo groupadd -g 250 -r ism
sudo useradd -g 250 -u 250 -m -d /var/lib/ism -s /bin/bash -r ism

Now clone the ISM git repository, and install ISM:

git clone https://github.com/fulgurance/ism
cd ism
crystal build --release Main.cr -o ism
sudo mv ism /usr/bin/ism
cd ..
sudo mv ism /usr/lib/ism
sudo chown root:root /usr/bin/ism
sudo chmod ugo+s /usr/bin/ism

ISM configuration

We will start to configure ISM to setup the root path, a proper make option to reduce the compilation time, synchronize the ports.

So first , set the root path where we will install the new system:

ism settings -srp /mnt/ism

(Optional): Set an appropriate job number, adapted to your virtual machine capacity (replace by the correct number), for the host and the new system:

ism settings -smo -j8
ism settings -scmo -j8

Open first the ports in your new system:

ism port open https://github.com/Fulgurance/Firmwares-Main
ism port open https://github.com/Fulgurance/Utilities-Main
ism port open https://github.com/Fulgurance/DisplayManagers-Main
ism port open https://github.com/Fulgurance/Shells-Main
ism port open https://github.com/Fulgurance/InitSystems-Main
ism port open https://github.com/Fulgurance/SecurityLibraries-Main
ism port open https://github.com/Fulgurance/BaseLibraries-Main
ism port open https://github.com/Fulgurance/KdeSoftwares-Main
ism port open https://github.com/Fulgurance/WebBrowsers-Main
ism port open https://github.com/Fulgurance/ProgrammingLanguages-Main
ism port open https://github.com/Fulgurance/ProgrammingTools-Main
ism port open https://github.com/Fulgurance/MultimediaSoftwares-Main
ism port open https://github.com/Fulgurance/NetworkingLibraries-Main
ism port open https://github.com/Fulgurance/GraphicsLibraries-Main
ism port open https://github.com/Fulgurance/Bootloaders-Main
ism port open https://github.com/Fulgurance/Fonts-Main
ism port open https://github.com/Fulgurance/Kernels-Main
ism port open https://github.com/Fulgurance/XorgBase-Main
ism port open https://github.com/Fulgurance/FileSystems-Main
ism port open https://github.com/Fulgurance/MultimediaLibraries-Main
ism port open https://github.com/Fulgurance/SystemBase-Main
ism port open https://github.com/Fulgurance/Components-Main
ism port open https://github.com/Fulgurance/ArchitectureComponents-Main
ism port open https://github.com/Fulgurance/SecuritySoftwares-Main
ism port open https://github.com/Fulgurance/NetworkingSoftwares-Main
ism port open https://github.com/Fulgurance/Archivers-Main
ism port open https://github.com/Fulgurance/Xml-Main
ism port open https://github.com/Fulgurance/WindowManagers-Main
ism port open https://github.com/Fulgurance/VideoDrivers-Main
ism port open https://github.com/Fulgurance/TextEditors-Main
ism port open https://github.com/Fulgurance/Terminals-Main
ism port open https://github.com/Fulgurance/KdeBase-Main
ism port open https://github.com/Fulgurance/InputDrivers-Main
ism port open https://github.com/Fulgurance/InputDriverLibraries-Main
ism port open https://github.com/Fulgurance/Sgml-Main
ism port open https://github.com/Fulgurance/Shells-Extra
ism port open https://github.com/Fulgurance/DatabaseLibraries-Main
ism port open https://github.com/Fulgurance/OfficeSoftwares-Main
ism port open https://github.com/Fulgurance/SystemGroups-Main
ism port open https://github.com/Fulgurance/SystemUsers-Main
ism port open https://github.com/Fulgurance/LanguageComponents-Main
ism port open https://github.com/Fulgurance/SystemTimezones-Main
ism port open https://github.com/Fulgurance/WebBrowsers-Main
ism port open https://github.com/Fulgurance/VirtualizationSoftwares-Main
ism port open https://github.com/Fulgurance/QtLibraries-Main

Now we synchronize them to get the last updates:

ism port synchronize

ISM is now ready to use !

3 - Install the system base

In this section, we will start now to install the cross toolchain and some temporary tools needed for the next steps.

First we must setup the system components. You can setup them manually or run the following command to setup them all with default values (everything will be disable by default):

ism system component -sa

Just before we install the minimal tools for a chroot, we need first to set the desire kernel, the default C library and the targeted architecture, or ism will complain about unselected unique dependencies:

ism software kernel-sources -sd linux-kernel-sources
ism software c-library -sd glibc
ism software architecture -sd x86

Now, start to install the minimal stuff for a chroot under the new system:

ism software install systembase

ISM will calculate all the dependencies we need , and just enter y for yes and then press enter to start the installation of the main base.

4 - Install the desired configuration

Then we can start to install a full plasma desktop environment.

The main configuration is managed by a virtual software called SystemConfiguration.

SystemConfiguration have as options other virtual softwares those manage the main components of the system. By this options, you can select the bootloader, kernel, init system, the used filesystems, languages, timezones, shells, loggers, crons, windowmanagers, desktop environments, display managers and graphical servers.

First for each components, we will select the options we need/want. We will in this example enable the support for the Openrc init.

ism software bootloader -eo grub
ism software grub -eo efibootmgr
ism software init -eo openrc
ism software filesystem -eo dosfstools
ism software filesystem -eo btrfs-progs
ism software filesystem -eo e2fsprogs
ism software language -eo english
ism software timezone -eo europe
ism software europe -eo london
ism software shell -eo bash
ism software cron -eo cronie
ism software logger -eo sysklogd
ism software windowmanager -eo kwin
ism software desktopenvironment -eo plasma-desktop
ism software displaymanager -eo sddm
ism software graphicalserver -eo xwayland
ism software graphicalserver -eo wayland
ism software graphicalserver -eo xorg-server
ism software alsa-lib -eo elogind
ism software libxkbcommon -eo wayland
ism software modemmanager -eo elogind
ism software polkit -eo elogind
ism software udisks -eo btrfs-progs
ism software udisks -eo dbus
ism software udisks -eo dosfstools
ism software udisks -eo elogind
ism software gtk -eo wayland
ism software gtk -eo wayland-protocols
ism software eudev -eo openrc
ism software alsa-utils -eo openrc
ism software @networkingSoftwares-main:dhcpcd -eo openrc
ism software networkmanager -eo openrc
ism software acpid -eo openrc
ism software chrony -eo openrc
ism software @utilities-main:cronie -eo openrc
ism software dbus -eo openrc
ism software power-profiles-daemon -eo openrc
ism software sysklogd -eo openrc
ism software tlp -eo openrc
ism software init -eo openrc
ism software wpa-supplicant -eo openrc
ism software elogind -eo openrc

Now we can install the configuration we setup:

ism software install systemconfiguration

Now actually, you finished to install all needed softwares for the very first base of your new linux system.

5 - Preparation for chroot

We are ready now to perform a chroot under the generated system to prepare the last details to be able to boot our new system properly.

First, we will install in our new system ism. For that, first install the required dependencies:

ism software install e2fsprogs crystal git

Mount the uefi partition:

sudo mount -t efivarfs none /mnt/ism/sys/firmware/efi/efivars

Then we can chroot under our system:

sudo chroot /mnt/ism

Now clone the ism repository and then install it:

git clone https://github.com/fulgurance/ism
mv ism /usr/lib/ism
cd /usr/lib/ism
crystal build --release Main.cr -o ism && cp ism /usr/bin/ism && rm ism && chmod ugo+s /usr/bin/ism && cd

The system is ready to setup the last things we need !

6 - Last setup before reboot

First under the chroot, we will install few softwares we will need.

ism software install nano \
                     iproute2 \
                     chrony \
                     dejavu-fonts-ttf \
                     alsa-utils \
                     sudo \
                     konsole \
                     upower \
                     tlp \
                     acpid \
                     power-profiles-daemon \
                     kbd \
                     procps-ng

Then configure the file /etc/fstab (this step depend how your partition the new system). The following text is just an example:

# <fs>                  <mountpoint>    <type>          <opts>                                          <dump/pass>

/dev/sda1               /boot           btrfs           defaults                                        0    2
/dev/sda2               /               btrfs           defaults                                        0    1

Set the hostname in /etc/hostname:

hostname

Now we will enable the required services:

rc-update add acpid default
rc-update add tlp default
rc-update add sysklogd boot
rc-update add alsasound boot
rc-update add dhcpcd default
rc-update add wpa-supplicant default
rc-update add networkmanager default
rc-update add elogind boot
rc-update add dbus default
rc-update add display-manager default
rc-update add udev sysinit
rc-update add udev-trigger sysinit
rc-update add chronyd default
rc-update add power-profiles-daemon default

Then we will setup the bootloader. First we will need to configure the kernel.

cd /usr/src/main-kernel-sources && make menuconfig

When you are happy with the configuration, now you can start to build it (substitute the number by the appropriate one for your virtual machine):

make -j8 modules_prepare && make -j8 && make -j8 modules_install && make -j8 install

Now we will install the bootloader:

grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=ISM

Setup the /etc/default/grub file according to your partition scheme. This is the minimal variables you will need to set (this is just an example):

GRUB_DISTRIBUTOR="ISM"
GRUB_CMDLINE_LINUX_DEFAULT="root=/dev/sda2 root_trim=yes selinux=0 enforcing=0 quiet"
GRUB_GFXPAYLOAD_LINUX=keep

Name the generated boot files and copy the current kernel config into /boot:

cd /boot && mv System.map System.map-linux-6.11.0 && mv vmlinuz vmlinuz-linux-6.11.0 && cp /usr/src/main-kernel-sources/.config /boot/config-linux-6.11.0

(Optional: Initramfs)

If it is required for your system, you can generate an initramfs, like to unlock encrypted filesystem for example:

With Ugrd (Recommended):

ism software install @bootloaders-main:ugrd
ugrd --force-out /boot/initramfs-6.11.0.cpio.xz

With Dracut:

ism software install @bootloaders-main:dracut
dracut --force --kver=6.11.0 /boot/initramfs-6.11.0.img

(Optional: Enable lvm and encryption at boot)

If it is required for your system, you can enable encryption via dmcrypt and lvm support at boot time:

rc-update add lvm boot
rc-update add dmcrypt boot

Then we can finally build the grub configuration:

grub-mkconfig -o /boot/grub/grub.cfg

And finally create a new user in the required groups to run sudo and use plasma properly:

useradd -m -G wheel,video,plugdev fulgurance
passwd fulgurance

And now before the reboot, just set the default display manager for your system in the file /etc/conf.d/display-manager:

DISPLAYMANAGER="sddm"

Conclusion

As you can see now, even the project is still in test, bit experimental at some part, it start to be really usable. I hope you will appreciate the work already done.

Enjoy !

This is the main page of the ISM wiki.

You will find here all available documentations:

Clone this wiki locally