Manual Installation guide

You will ocassionally see a $ before a command. This is mostly to differentiate the input (what you type), from the output, the computer provides.

Here’s an example:

$ lsblk
NAME          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
sda             8:0    0 465.8G  0 disk
└─sda1          8:1    0 465.8G  0 part  /media/franz/4e619844-b92a-49bd-8b70-cf934abdc8eb

So the actual command is lsblk (you don’t write $).

On the other hand, if there’s only a command, and no output, we sometimes omit the $ like so:

lsblk

Pre-installation

Before you get started, ready a USB stick with the latest ISO image.

Download pantherx-19-09-2023.iso (1.5GB)
19xzxwk2zi4l2f4lzav2v1vzk52794gv3vb1kgnhc52zx1wk3dc3

Flash with dd

Plugin the USB stick and determine the name:

$ lsblk
NAME          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
sda             8:0    1  14.9G  0 disk
├─sda1          8:1    1     1G  0 part  /media/franz/GUIX_IMAGE
└─sda2          8:2    1   2.8M  0 part
nvme0n1       259:0    0 953.9G  0 disk
├─nvme0n1p1   259:1    0   549M  0 part  /boot/efi
└─nvme0n1p2   259:2    0 953.3G  0 part
  └─cryptroot 253:0    0 953.3G  0 crypt /

In my case, it’s /dev/sda, so I proceed with copying the ISO to this drive:

$ sudo dd if=pantherx-19-09-2023.iso of=/dev/sda status=progress
Password:
1110499840 bytes (1.1 GB, 1.0 GiB) copied, 284 s, 3.9 MB/s
2169320+0 records in
2169320+0 records out
1110691840 bytes (1.1 GB, 1.0 GiB) copied, 284.985 s, 3.9 MB/s
$ sync

Now unmount / eject the drive:

sudo umount /dev/sda1

Flash with etcher

If you prefer a GUI tool that runs on your existing OS (Windows, MacOS, other Linux), have a look at etcher.

First steps

Now just plugin the USB stick into the target computer, and boot from it. Most commonly, you can get a boot device selection with F11.

Once you have booted from USB, you will be greeted with “Locale language” selection.

Select your locale
Select your region

The graphical installation is not quite ready yet, so we’ll proceed manually.

Select “Install using the shell based process”.

Connect to the Internet

Now that you’re in the command like, you should read “Welcome to the Installation of PantherX OS!”. Before we get continue, we need to establish a internet connection. If you are connected with a LAN cable, that might already have happened.

Here’s how you verify whether you’re connected:

$ ifconfig -a
eno1      Link encap:Ethernet  HWaddr A8:A1:59:5E:FB:D9
          UP BROADCAST MULTICAST DYNAMIC  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:0  TX bytes:0
          Interrupt:16 Memory:a1200000-a1220000

enp2s0    Link encap:Ethernet  HWaddr A8:A1:59:5E:FC:A0
          inet addr:192.168.1.69  Bcast:192.168.1.255  Mask:255.255.255.0  # <-- valid IP
          UP BROADCAST RUNNING MULTICAST DYNAMIC  MTU:1500  Metric:1
          RX packets:71 errors:0 dropped:0 overruns:0 frame:0
          TX packets:104 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:12868  TX bytes:19744

lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Bcast:0.0.0.0  Mask:255.0.0.0
          UP LOOPBACK RUNNING  MTU:65536  Metric:1
          RX packets:19 errors:0 dropped:0 overruns:0 frame:0
          TX packets:19 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:3485  TX bytes:3485

One of the listed interfaces, should have a valid IP address. For example 192.168.1.69. If that’s the case, you can proceed to the next step. If not, here’s how you connect:

Wired Network (LAN)

To configure a wired network run the following command, substituting interface with the name of the wired interface you want to use:

$ ifconfig INTERFACE_NAME up

# Example
$ ifconfig enp2s0 up

Now try to get a IP address:

$ dhclient -v INTERFACE_NAME

# Example
$ dhclient -v enp2s0

Wireless Network (WLAN)

To configure wireless networking, create a configuration file for the wpa_supplicant configuration tool:

$ nano wpa_supplicant.conf

with the following content:

network={
  ssid="YOUR_WIFI_NAME"
  key_mgmt=WPA-PSK
  psk="YOUR_WIFI_PASSWORD"
}

once you’re done, this should look roughly like this:

network={
  ssid="MyWirelessNetwork"
  key_mgmt=WPA-PSK
  psk="3295e09f-241b-4a06-a492-f3f3cc95c24d"
}

To start the wireless service, and run it on interface in the background:

$ wpa_supplicant -c wpa_supplicant.conf -i INTERFACE_NAME -B

# Example
$ wpa_supplicant -c wpa_supplicant.conf -i enp2s0 -B

Note If this doesn’t work, you might want to try to check your network with rfkill:

$ rfkill
ID TYPE      DEVICE                   SOFT      HARD
 0 bluetooth tpacpi_bluetooth_sw unblocked unblocked
 1 bluetooth hci0                unblocked unblocked
 2 wlan      phy0                unblocked unblocked

If the wlan interface is blocked, you can unblock it with sudo rfkill unblock wlan. You should run wpa_supplicant -c ... after you unblock the device.

Now try to get a IP address:

$ dhclient -v INTERFACE_NAME

# Example
$ dhclient -v enp2s0

SSH access (OPTIONAL)

If you want to continue with the installation remotely, load the SSH server and set a root password:

$ herd start ssh-daemon
Service ssh-daemon has been started.
$ passwd
New Password:
Retype new password:
passwd: password updated successfully

Now simply connect via SSH from another computer: ssh root@192.168.1.67.

Partition and format the disks

Depending on your PC, you should either install with BIOS or EFI support. EFI support is only available on newer PC’s, yet BIOS support should always work.

Before you get started, make sure you target the right hard disk:

$ lsblk
NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
sda      8:0    0 59.6G  0 disk
└─sda1   8:1    0 59.6G  0 part
sdb      8:16   1 14.9G  0 disk
├─sdb1   8:17   1    1G  0 part
└─sdb2   8:18   1  2.8M  0 part

In this case, sda will be out target disk.

BIOS-Boot (OPTION 1)

Let’s partition

cfdisk /dev/sda

Create a boot partition with the capacity of 2M and BIOS Boot type
Create a system partition with the capacity of whatever is remaining (59.4G) and Linux filesystem (Default)

Make sure that it looks roughly like this:

Device			Start			End				Sectors			Size 		Type
/dev/sda1       2048            6143          	4096          	2M 			BIOS boot
/dev/sda2   	6144          	125045390       125039246       59.4G 		Linux filesystem

Next, format the second partitions:

mkfs.ext4 -L my-root /dev/sda2

EFI-Boot (OPTION 2)

First we need to ensure that the target disk follows the GPT format:

parted /dev/sda mklabel gpt --script

Let’s partition

cfdisk /dev/sda

Create a boot partition with the capacity of 200M and EFI System type
Create a system partition with the capacity of whatever is remaining (59.4G) and Linux filesystem (Default)

Make sure that it looks roughly like this:

Device			Start			End				Sectors			Size 		Type
/dev/sda1       2048            411647          409600          200M 		EFI System
/dev/sda2   	411648          125045390       124633743       59.4G 		Linux filesystem

Now set the esp flag:

parted /dev/sda set 1 esp on

Next, format the two partitions:

mkfs.fat -F32 /dev/sda1
mkfs.ext4 -L my-root /dev/sda2

and mount the EFI partition at /boot/efi

mkdir /boot/efi
mount /dev/sda1 /boot/efi

Mount the file systems

mount LABEL=my-root /mnt

Swap space

This is somewhat optional but highly recommended. If your computer runs out of memory (RAM), it can utilize the swap space, to store the data. This is a 1000x times slower than RAM but will prevent your computer from locking-up.

Here’s how you create a swap space:

If you have 4GB of RAM, a count of 4096 (as in 4096 MB) is recommended.

$ dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=4096
4096+0 records in
4096+0 records out
4294967296 bytes (4.3 GB, 4.0 GiB) copied, 34.4218 s, 125 MB/s
$ chmod 600 /mnt/swapfile
$ mkswap /mnt/swapfile
Setting up swapspace version 1, size = 4 GiB (4294963200 bytes)
no label, UUID=ea7cc142-1225-48a1-b68d-dd5c9a958938
$ swapon /mnt/swapfile

Installation

Now we’re ready to kick-off the actual installation!

$ herd start cow-store /mnt
Service cow-store has been started.

Configure the system

First we will have to create a folder, to hold our new system configuration:

$ mkdir /mnt/etc

Create the file with:

$ nano /mnt/etc/system.scm

See Option 1 and 2 below.

You’ll need to modify some details:

host-name (px-base): This is what your computer will be called on the network
timezone (Europe/Berlin). You can find a list of all time zones here

Under users, adapt the user account:

name: This is a one-word, lowercase username such as franz
home-directory: should reflect the username: /home/franz

System configuration BIOS-boot (OPTION 1)

If you followed the bios boot partitioning steps, your system configuration should look like this. Make sure that you adapt it to your needs!

You can ignore the other settings for now.

;; PantherX OS Desktop Configuration v2
;; boot in "legacy" BIOS mode
;; /etc/system.scm

(use-modules (gnu)
             (gnu system)
             (gnu services desktop)
             (px system config))

(px-desktop-os
 (operating-system
  (host-name "px-base")
  (timezone "Europe/Berlin")
  (locale "en_US.utf8")
  
  ;; Boot in "legacy" BIOS mode, assuming /dev/sda is the
  ;; target hard disk, and "my-root" is the label of the target
  ;; root file system.
  (bootloader (bootloader-configuration
               (bootloader grub-bootloader)
               (targets '("/dev/sda"))))
  
  (file-systems (cons (file-system
                       (device (file-system-label "my-root"))
                       (mount-point "/")
                       (type "ext4"))
                      %base-file-systems))
  
  (users (cons (user-account
                (name "panther")
                (comment "panther's account")
                (group "users")
                ;; Set the default password to 'pantherx'
                ;; Important: Change with 'passwd panther' after first login
                (password (crypt "pantherx" "$6$abc"))
		
                ;; Adding the account to the "wheel" group
                ;; makes it a sudoer.  Adding it to "audio"
                ;; and "video" allows the user to play sound
                ;; and access the webcam.
                (supplementary-groups '("wheel"
                                        "audio" "video"))
                (home-directory "/home/panther"))
               %base-user-accounts))
  
  ;; Globally-installed packages.
  (packages (cons*
	     %px-desktop-packages))
  
  ;; Globally-activated services.
  (services (cons*
             (service xfce-desktop-service-type)
	     %px-desktop-services))))

System configuration EFI-boot (OPTION 2)

Create the file with:

$ nano /mnt/etc/system.scm

If you followed the EFI boot partitioning steps, your system configuration should look like this. Make sure that you adapt it to your needs!

You can ignore the other settings for now.

;; PantherX OS Desktop Configuration v2
;; boot in EFI mode
;; /etc/system.scm

(use-modules (gnu)
             (gnu system)
             (gnu services desktop)
             (px system config))

(px-desktop-os
 (operating-system
  (host-name "px-base")
  (timezone "Europe/Berlin")
  (locale "en_US.utf8")
  
  ;; Boot in EFI mode, assuming /dev/sda is the
  ;; target hard disk, and "my-root" is the label of the target
  ;; root file system.
  (bootloader (bootloader-configuration
               (bootloader grub-efi-bootloader)
               (targets '("/boot/efi"))))
  
  (file-systems (append
		 (list (file-system
			(device (file-system-label "my-root"))
			(mount-point "/")
			(type "ext4"))
		       (file-system
			(device "/dev/sda1")
			(mount-point "/boot/efi")
			(type "vfat")))
		 %base-file-systems))
  
  (users (cons (user-account
                (name "panther")
                (comment "panther's account")
                (group "users")
                ;; Set the default password to 'pantherx'
                ;; Important: Change with 'passwd panther' after first login
                (password (crypt "pantherx" "$6$abc"))
		
                ;; Adding the account to the "wheel" group
                ;; makes it a sudoer.  Adding it to "audio"
                ;; and "video" allows the user to play sound
                ;; and access the webcam.
                (supplementary-groups '("wheel"
                                        "audio" "video"))
                (home-directory "/home/panther"))
               %base-user-accounts))
  
  ;; Globally-installed packages.
  (packages (cons*
	     %px-desktop-packages))
  
  ;; Globally-activated services.
  (services (cons*
             (service xfce-desktop-service-type)
	     %px-desktop-services))))

Channels

Once you’ve set the system configuration, we put in place the channels in place. These work much like repositories on other Linux distribution… This is where your software comes from!

Create the file with:

$ mkdir /mnt/etc/guix
$ nano /mnt/etc/guix/channels.scm

with the following content:

(cons* (channel
        (name 'pantherx)
        (branch "master")
        (url "https://channels.pantherx.org/git/panther.git")
         (introduction
          (make-channel-introduction
           "54b4056ac571611892c743b65f4c47dc298c49da"
           (openpgp-fingerprint
            "A36A D41E ECC7 A871 1003  5D24 524F EB1A 9D33 C9CB"))))
       %default-channels)

Update and install

Once you’re satisfied with your configuration, proceed with the installation.

First we’ll pull the latest packages:

$ guix pull --channels=/mnt/etc/guix/channels.scm
Updating channel 'guix' from Git repository at 'https://channels.pantherx.org/git/panther.git'...
receiving objects  37% [####################################################################
...
hint: After setting `PATH', run `hash guix' to make sure your shell refers to `/root/.config/guix/current/bin/guix'.

Lastly, run:

hash guix

Once that’s done, initiate the system

$ guix system init /mnt/etc/system.scm /mnt
substitute: updating substitutes from 'https://ci.guix.gnu.org'... 100.0%
substitute: updating substitutes from 'https://bordeaux.guix.gnu.org'... 100.0%
substitute: updating substitutes from 'https://build.pantherx.org'... 100.0%
242.6 MB will be downloaded
 usb-modeswitch-data-20191128  19KiB
 ...
guix system: bootloader successfully installed on '/dev/sda'

Reboot

After completion, reboot.

Tip: SSH is disabled by default on Desktop so you won’t be able to reconnect after reboot without enabling it first

Post-installation

Once you login for the first time, there’s a couple of things to be aware of.

(1) General

We highly recommend you to run an initial update, before you get started.

Open ‘System Tools’ > ‘Terminal’
Apply both user and system updates

px update apply # initial user update
su - root
px update apply # initial root updaye
reboot

This will also ensure that you do not run into this issue: Opening Folders from Directory Menu failed

(2) Set new user and root password

Open ‘System Tools’ > ‘Terminal’
Set a root password with sudo passwd
Set a user password with passwd YOUR_USERNAME

Have a great time on PantherX OS

Pre-installation

Flash with dd

Flash with etcher

First steps

Connect to the Internet

Wired Network (LAN)

Wireless Network (WLAN)

SSH access (OPTIONAL)

Partition and format the disks

BIOS-Boot (OPTION 1)

EFI-Boot (OPTION 2)

Mount the file systems

Swap space

Installation

Configure the system

System configuration BIOS-boot (OPTION 1)

System configuration EFI-boot (OPTION 2)

Channels

Update and install

Reboot

Post-installation

First login:

(1) General

(2) Set new user and root password