Installing joe Linux
The installation medium is a live GNOME session with an installer. It puts joe Linux beside the system already on a disk, in its free space, or on a whole disk.
What you need
- A computer with UEFI firmware, with Secure Boot turned off. joe Linux does not start on BIOS-only machines, and it is not signed for Secure Boot.
- 22 GB of free space on a disk, beside the system already there (see Beside Windows), or a disk of at least 20 GB that you are willing to erase completely. The installer does not encrypt the disk.
- A USB stick big enough for the image (1.8 GB), or a virtual machine.
joe Linux is in beta. Install it on a computer, or a virtual machine, whose contents do not matter. The hardware list has the computers it has been installed on.
Download it
The newest medium is J1-7.3.1-0.4.0-beta1: joe-J1-7.3.1-0.4.0-beta1-x86_64.iso. Earlier ones are on the downloads page.
Check the download
The file’s SHA-256 checksum is in SHA256SUMS. With both files in one directory:
$ sha256sum --check --ignore-missing SHA256SUMS
joe-J1-7.3.1-0.4.0-beta1-x86_64.iso: OK
Anything other than OK means the file is damaged or incomplete; download it again.
Write it to a USB stick
In GNOME, open Disks, choose the USB stick, then Restore Disk Image from its menu, and pick the file.
From a terminal, find the stick’s device name with lsblk and write the image to the whole device (not a partition such as /dev/sdX1). Everything on the stick is lost:
$ sudo dd if=joe-J1-7.3.1-0.4.0-beta1-x86_64.iso of=/dev/sdX bs=4M status=progress oflag=sync
The medium is a hybrid image, so the same file works as a USB stick and as a CD.
Or try it in a virtual machine
Give the machine UEFI firmware (in virt-manager, choose UEFI when you create it; in QEMU, OVMF), attach the file as a CD, and add an empty disk of at least 20 GB. joe Linux’s own tests give the live session 6 GB of memory. With QEMU directly, on Arch Linux:
$ truncate -s 40G disk.img
$ cp /usr/share/edk2/x64/OVMF_VARS.4m.fd vars.fd
$ qemu-system-x86_64 -enable-kvm -cpu host -machine q35 -m 6G -smp 4 \
-drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/x64/OVMF_CODE.4m.fd \
-drive if=pflash,format=raw,file=vars.fd \
-drive file=disk.img,format=raw,if=virtio \
-drive if=none,id=medium,format=raw,media=cdrom,readonly=on,file=joe-J1-7.3.1-0.4.0-beta1-x86_64.iso \
-device ide-cd,drive=medium,bootindex=0 \
-device virtio-vga -netdev user,id=n0 -device virtio-net-pci,netdev=n0
Other distributions keep the OVMF files elsewhere, for example /usr/share/OVMF/OVMF_CODE_4M.fd on Debian.
Start from the medium
Choose the USB stick in your computer’s boot menu (often F12, F10 or Esc while it starts). A GNOME session starts from a compressed image of the desktop, with a layer in memory for changes, and opens the installer. Nothing you do in the live session is kept.
Install
The installer lists your disks. A disk it cannot use is shown with the reason: it holds the medium you started from, it is read-only, it is smaller than 20 GB, or part of it is in use. Installing beside another system also needs a GPT partition table, an EFI system partition to share, and 22 GB of free space in one piece; when one of those is missing, the installer says which.
Choose a disk, then how to use it:
- Install beside the system already there, in the disk’s largest free space. Nothing on the disk is moved, shrunk or erased.
- Erase the disk, and give all of it to joe Linux.
The last page asks two more things, and needs neither:
- Enforce the security module. The installed system then starts with the module refusing what a privileged program has not declared, instead of only recording it (see logging and enforcing). It is off unless you tick it. The desktop and a fresh installation are tested enforcing; printing, Bluetooth, modems and ssh logins are not yet.
- Accounts. To bring over the accounts and homes of another Linux system, open that system’s disk in Files and choose Look Again, and the installer offers it. The accounts keep their passwords and groups, and those who could administer that system can administer this one. The other system must be on another disk than the one you install onto.
Confirm, and the installer:
- beside another system, adds a small boot partition and a btrfs root to the free space and shares the disk’s EFI system partition; on an erased disk, writes a new GPT partition table with an EFI system partition and a btrfs root, laid out as every joe system’s;
- installs the packages from the medium itself, in one dave transaction, without the network: it copies them out of the live session’s own image and checks every file against its package;
- seals the files as it installs them, so the first start has nothing left to seal;
- tells the firmware where the boot loader is;
- brings the accounts over, if you chose to, with pour. Files in their homes lose any setuid and setgid bits.
The installer is a front end to dave install-system, which you can also run yourself in the live session’s terminal:
$ sudo dave install-system --list
$ sudo dave install-system --disk /dev/nvme0n1 --beside
$ sudo dave install-system --disk /dev/nvme0n1
$ sudo dave install-system --disk /dev/nvme0n1 --enforce
$ sudo dave install-system --disk /dev/nvme0n1 --import /mnt/old
--import takes the directory the other system is mounted at.
Beside Windows
Make room for joe Linux in Windows first: open Disk Management, right-click the Windows partition, choose Shrink Volume, and shrink it by at least 22 GB (the box counts in MB: enter 22528 or more). Then start the medium and choose Install beside Windows.
This works with a Windows that starts through UEFI, as Windows 11 requires. A Windows installed for a BIOS starts from an MBR partition table with no EFI system partition, which joe Linux cannot share.
joe Linux adds only its boot loader, systemd-boot, to the EFI system partition Windows uses, and keeps its kernels on its own boot partition. When the computer starts, a menu lists joe Linux and Windows for five seconds and starts joe Linux unless you choose Windows.
If Windows encrypts its disk with BitLocker, have its recovery key at hand: Windows may ask for it the first time it starts from the new menu.
The first start
Remove the medium and restart. joe Linux starts without an initramfs, and GNOME’s initial setup asks for your language, keyboard layout and time zone and creates your account. That account is an administrator (a member of wheel), so sudo works. The root account itself is locked.
If you brought accounts over, there is no initial setup: GDM lists those accounts, and the language, keyboard layout and time zone stay at their defaults until you change them in Settings.
The installed system upgrades from the same repository the medium was made from. To bring it up to date:
$ sudo dave upgrade
$ systemctl reboot
Using dave explains what that does, and how to go back.
Or try it in a container
joe Linux’s command line, with dave, is also a container image. It needs nothing but Docker or Podman:
$ docker run -it ghcr.io/thejoelinuxfoundation/joe
# dave install git
A container runs on its host’s kernel, so there is no desktop, no upgrades by reboot and no security module in it; dave installs and upgrades packages in place.