Guide

Avant de commencer

N'importe quel ordinateur x86 64 bits. Le programme d'installation demande au moins 1,7 Go de RAM et 18 Go d'espace disque ; les valeurs ci-dessous sont celles avec lesquelles le système tourne à l'aise.

Le même fichier prend en charge l'UEFI comme le BIOS classique. Secure Boot peut rester activé.

Télécharger et vérifier

L'image tient dans un seul fichier, moonlightos-26.04.5-bengunur-amd64.iso, accompagné d'un second qui contient sa somme de contrôle SHA-256. Vérifiez cette somme avant d'écrire l'image : un téléchargement incomplet donne une clé USB qui démarre, puis échoue de façon déroutante.

Sous Linux ou macOS, dans le dossier où vous avez enregistré le téléchargement :

sha256sum -c moonlightos-26.04.5-bengunur-amd64.iso.sha256

Sous Windows, dans PowerShell, comparez l'empreinte affichée avec celle du fichier .sha256 :

Get-FileHash .\moonlightos-26.04.5-bengunur-amd64.iso -Algorithm SHA256
Get-Content .\moonlightos-26.04.5-bengunur-amd64.iso.sha256

La première commande affiche OK ; la seconde affiche une empreinte qui doit correspondre à celle du fichier. Toute autre réponse signifie que le téléchargement est abîmé.

Télécharger 26.04.5

Copier l'image sur une clé USB

L'image est une ISO hybride : une simple copie bloc à bloc suffit, aucun outil particulier n'est nécessaire, et la même clé démarre aussi bien sur un ordinateur UEFI que sur un ordinateur BIOS. Tout le contenu de la clé est effacé. Il vous faut une clé de 8 Go au minimum.

Sous Linux ou macOS, repérez d'abord le nom du périphérique (lsblk sous Linux, diskutil list sous macOS), puis :

sudo dd if=moonlightos-26.04.5-bengunur-amd64.iso of=/dev/sdX bs=4M status=progress oflag=direct conv=fsync

sudo dd if=moonlightos-26.04.5-bengunur-amd64.iso of=/dev/rdiskN bs=4m   # macOS

Vérifiez deux fois le nom du périphérique : dd écrit sur celui qu'on lui désigne, quel qu'il soit.

Windows

Utilisez Rufus en mode image DD, balenaEtcher ou Ventoy. Si Rufus demande d'écrire en mode ISO ou DD, choisissez DD.

Démarrer depuis la clé USB

Allumez l'ordinateur avec la clé insérée et ouvrez le menu de démarrage ponctuel (F12, F8, F2, Échap ou Suppr selon le fabricant), ou désignez le périphérique USB comme premier support de démarrage dans les réglages du micrologiciel. Il n'y a rien à changer du côté de Secure Boot.

Le menu de démarrage

• Try or Install MoonLightOS

  L'entrée normale. Elle démarre la session live avec l'animation de démarrage.

• Try or Install MoonLightOS (safe graphics)

  La même, avec le mode graphique du noyau désactivé. À utiliser quand l'écran reste noir ou que l'affichage est brouillé.

• MoonLightOS in RAM (needs 6 GB+)

  Copie tout le système en mémoire : la clé peut ensuite être retirée.

• Check this medium for defects

  Contrôle chaque fichier de la clé par rapport aux sommes enregistrées à la construction.

• Verbose boot (no splash, logs to serial)

  Affiche tous les messages à l'écran et sur le premier port série, seul moyen de lire un démarrage qui échoue avant que l'affichage soit disponible.

• UEFI firmware settings

  Redémarre dans les réglages du micrologiciel.

La session live

La première chose qui s'affiche est l'assistant de configuration : choisissez la langue du système, confirmez la disposition du clavier (tapez dans le champ pour l'essayer), connectez-vous à un réseau Wi-Fi, puis explorez ou installez. Tout ce qu'il définit est un véritable paramètre du système, que le programme d'installation reprend tel quel.

La session live est le système complet, tel quel : même bureau, mêmes outils, mêmes pages de paramètres. L'utilisateur live s'appelle moonlight et n'a pas de mot de passe. Rien de ce que vous faites ici ne touche au disque avant que vous lanciez le programme d'installation.

Pour installer, double-cliquez sur Installer MoonLightOS sur le bureau, ou rouvrez l'assistant Configuration et choisissez Installer.

Installer

Le programme d'installation est Calamares. Sept pages, puis la copie sur le disque.

1. Bienvenue

   La langue du programme d'installation et les liens vers ce guide.

2. Localisation

   Votre région et votre fuseau horaire ; la locale et les formats de nombres en découlent.

3. Clavier

   Déjà réglé sur ce que vous avez choisi dans l'assistant. Tapez dans le champ pour le vérifier.

4. Partitions

   Effacer le disque est la proposition par défaut et crée un système de fichiers ext4 avec un fichier d'échange ; btrfs, xfs et f2fs sont également disponibles, de même que le partitionnement manuel. Cochez Chiffrer le système pour le chiffrement intégral LUKS2 et choisissez une phrase secrète : vous la taperez à chaque démarrage, et elle est irrécupérable en cas d'oubli. Sur un ordinateur UEFI, une partition EFI de 512 Mio est créée.

5. Utilisateurs

   Votre nom, le nom de l'ordinateur, un identifiant et un mot de passe de huit caractères au moins, puisés dans deux catégories. Le premier compte administre l'ordinateur au travers de sudo ; le compte root reste verrouillé, et il n'y a pas d'ouverture de session automatique, à moins que vous ne l'activiez.

6. Résumé

   Tout ce que le programme d'installation va faire, en une seule liste. Rien n'a encore été écrit.

7. Installation

   Le système est copié sur le disque, le chargeur de démarrage est installé (sous le nom MoonLightOS dans la liste de démarrage du micrologiciel en UEFI), et les restes de la session live sont supprimés. Il n'y a plus qu'à redémarrer et retirer la clé.

Les autres systèmes d'exploitation présents sur l'ordinateur sont détectés par os-prober au premier démarrage et ajoutés au menu GRUB.

Le premier démarrage

Un système fraîchement installé est la copie exacte de l'image dont sortent toutes les autres installations. Tout ce qui doit être propre à cet ordinateur est créé au premier démarrage, avant l'apparition de l'écran d'ouverture de session, par un service qui se désactive ensuite lui-même :

• un nouvel identifiant de machine, pour qu'aucun observateur du réseau ne puisse rapprocher deux installations ;
• de nouvelles clés d'hôte SSH, car une clé commune à tous ceux qui ont téléchargé l'image ôterait tout sens à la vérification de l'hôte ;
• le menu GRUB, maintenant que les vrais disques et les systèmes d'exploitation qu'ils portent sont visibles ;
• un initramfs reconstruit pour le matériel réellement présent, donc plus petit, ce qui fait apparaître l'animation de démarrage plus tôt ;
• les caches d'icônes, de polices et du bureau, pour que la première ouverture de session ne traîne pas ;
• le pare-feu, réactivé.

Sa sortie est écrite dans /var/log/moonlight-firstboot.log. Puis l'écran d'ouverture de session apparaît et, après la première connexion, la fenêtre Bienvenue.

Premiers pas

• Choisir une apparence

  Sombre ou clair, directement dans Bienvenue. Tout le reste est dans MoonLight Tweaks : la disposition du bureau, le fond d'écran, l'horaire et les gadgets.

• Pilotes

  Bienvenue → Pilotes ouvre le gestionnaire de pilotes. Sur un ordinateur à carte NVIDIA, le pilote propriétaire se trouve sur l'ISO : il fonctionne donc sans connexion Internet.

• Logiciels

  La logithèque réunit les snaps, le dépôt Ubuntu et Flathub. Thunderbird, Steam, Spotify et bien d'autres s'y trouvent en une recherche.

• Empreinte et visage

  Bienvenue → Empreinte digitale, ou Paramètres système → Votre compte, pour enregistrer une empreinte ou configurer le déverrouillage par le visage.

• Sauvegardes

  Timeshift prend des instantanés du système selon un horaire. Configurez-le avant d'en avoir besoin.

• Sécurité

  Paramètres système → Sécurité montre ce qui protège ou non cet ordinateur, chaque ligne accompagnée du bouton qui règle le problème.

• Packs de développement

  Machines virtuelles, PHP avec bases de données et LaTeX : un clic chacun dans Bienvenue, installés depuis le dépôt déjà configuré.

• Programmes Windows

  Ouvrez Applications Windows une fois : l'outil prépare Wine avec DXVK, VKD3D, les polices et les bibliothèques d'exécution. Ensuite, un fichier .exe s'ouvre tout simplement.

Machines virtuelles

VirtualBox

Trois réglages de VirtualBox doivent être changés, sinon il refuse purement et simplement de démarrer cette image. La panne ressemble à un manque de mémoire, mais n'en est pas un : GRUB passe en mode graphique pour dessiner son menu décoré, et avec les 16 Mo de mémoire vidéo que VirtualBox attribue par défaut, l'opération échoue sur le message « Out of memory. You need to load the kernel first. »

En ligne de commande :

VBoxManage modifyvm "MoonLightOS" \
    --ostype Ubuntu24_LTS_64 --memory 4096 --cpus 4 \
    --vram 128 --graphicscontroller vmsvga --accelerate3d on \
    --boot1 dvd --boot2 disk

VirtualBox étiquette le support « Ubuntu » parce qu'il y trouve un dossier /casper. Ce n'est qu'une étiquette dans son interface : le support lui-même s'identifie comme MoonLightOS. Choisissez tout de même le type d'invité Ubuntu : c'est lui qui donne le bon jeu de puces et les bons réglages graphiques.

QEMU

En UEFI, comme la plupart des ordinateurs aujourd'hui. Créez d'abord les variables de micrologiciel inscriptibles et un disque de destination :

cp /usr/share/OVMF/OVMF_VARS.fd .
qemu-img create -f qcow2 disk.qcow2 30G
qemu-system-x86_64 \
  -enable-kvm -m 4096 -smp 4 \
  -machine q35 -cpu host \
  -device virtio-vga-gl -display gtk,gl=on \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
  -drive if=pflash,format=raw,file=OVMF_VARS.fd \
  -drive file=moonlightos-26.04.5-bengunur-amd64.iso,media=cdrom \
  -drive file=disk.qcow2,if=virtio

Avec Secure Boot réellement actif, à l'aide du micrologiciel où les clés de Microsoft sont enregistrées. Une fois le système démarré, mokutil --sb-state indique SecureBoot enabled, et Paramètres → À propos le confirme :

cp /usr/share/OVMF/OVMF_VARS_4M.ms.fd OVMF_VARS.fd
qemu-system-x86_64 \
  -enable-kvm -m 4096 -smp 4 -machine q35,smm=on -cpu host \
  -global driver=cfi.pflash01,property=secure,value=on \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.secboot.fd \
  -drive if=pflash,format=raw,file=OVMF_VARS.fd \
  -drive file=moonlightos-26.04.5-bengunur-amd64.iso,media=cdrom

En BIOS classique : l'ISO est hybride, donc le même fichier démarre aussi à l'ancienne :

qemu-system-x86_64 -enable-kvm -m 2048 -cdrom moonlightos-26.04.5-bengunur-amd64.iso

Pour mettre la promesse des 2 Go à l'épreuve, démarrez sans accélération et avec le minimum de mémoire, puis vérifiez dans la session live que zram apparaît comme espace d'échange et que la pression mémoire reste faible :

qemu-system-x86_64 -enable-kvm -m 2048 -smp 2 -vga std -cdrom moonlightos-26.04.5-bengunur-amd64.iso

# in the live session:
free -h                      # zram appears as swap
swapon --show                # /dev/zram0, zstd
cat /proc/pressure/memory    # "some avg10" under about 10 means it is keeping up
systemctl is-active earlyoom

Les outils invité pour VirtualBox, QEMU/SPICE et VMware sont déjà sur l'image : c'est de là que viennent le redimensionnement de l'affichage et le partage du presse-papiers.

Raccourcis clavier

Le tableau complet se trouve sur la page Fonctionnalités. Voici ceux qui méritent d'être appris dès le premier jour :

Le tableau complet

En cas de problème

• L'écran reste noir après le menu de démarrage

  Choisissez l'entrée safe graphics. Si le système démarre, lancez l'installation depuis cette session, puis activez le pilote propriétaire depuis la page Pilotes.

• « Out of memory. You need to load the kernel first. »

  Une machine VirtualBox avec 16 Mo de mémoire vidéo. Donnez-lui 128 Mo et activez l'accélération 3D ; voyez Machines virtuelles plus haut.

• Le bureau paraît lent

  Regardez le moteur de rendu OpenGL dans Paramètres → À propos. Avec un rendu logiciel, les animations se désactivent toutes seules à l'ouverture de session ; Tweaks → Performances les désactive à la main.

• La clé démarre, puis échoue de façon déroutante

  Lancez Check this medium for defects depuis le menu de démarrage, et vérifiez la somme SHA-256 du téléchargement.

• Pas de Wi-Fi

  Ouvrez la page Pilotes : le pilote Broadcom se trouve sur l'image. Pour les autres adaptateurs, le menu réseau liste ce que le noyau a détecté.

• Le lecteur d'empreinte n'est pas détecté

  Ouvrez Empreinte digitale. L'outil nomme le fabricant du capteur, dit s'il est natif, à comparaison embarquée ou à binaire propriétaire, et explique ce qu'il est possible de faire.

• Consulter les journaux

  Ce dont le démarrage s'est plaint, le journal du gestionnaire de session, celui du premier démarrage, et le nom du thème de démarrage actif :

journalctl -b -p warning          # what the boot complained about
journalctl -b -u lightdm
cat /var/log/moonlight-firstboot.log
plymouth-set-default-theme        # should print: moonlightos

Pour un rapport de bogue, À propos → Copier le rapport place la version et le matériel dans le presse-papiers, et moonlight-selftest affiche ce que fait réellement le bureau.

moonlight-selftest | less

Construire soi-même

Toute la distribution tient dans un seul dépôt : les visuels dérivent d'un logo source unique, les thèmes sortent d'une palette unique, et un seul script transforme l'ensemble en une image ISO amorçable compatible Secure Boot. Il vous faut Docker et environ 25 Go d'espace libre ; le système d'exploitation importe peu, puisque tout se déroule dans un conteneur.

L'ISO est écrite dans out/, avec sa somme SHA-256 à côté. Sous Windows, lancez la construction depuis Git Bash ou utilisez build.ps1.

Comment la construction est organisée

Avant la création de l'ISO, la construction exécute plus de 120 contrôles obligatoires à l'intérieur de l'image : le noyau, le shim signé, les deux thèmes, chaque MoonTool, les codecs, les pilotes Wi-Fi, les traductions, et le fait que le déverrouillage par le visage et le mot de passe d'urgence sont bien inactifs. Au premier contrôle en échec, la construction s'arrête. L'espace de travail est un volume Docker et non un montage lié, parce que les propriétaires de fichiers, les liens symboliques et les nœuds de périphériques ne survivent pas à un montage lié sous Windows ou macOS.

Personnaliser

• L'identité de la distribution

  config/moonlight.conf contient toutes les chaînes qui définissent la distribution.

• Les visuels

  Remplacez le logo source ou un fond d'écran, relancez tools/gen-branding.py, et l'animation de démarrage, GRUB, l'écran d'ouverture de session, les icônes et les visuels du programme d'installation sont tous régénérés.

• Les couleurs

  tools/gen-themes.py contient une palette sombre et une palette claire, et produit les deux thèmes complets selon les mêmes règles.

• Les paquets installés

  packages/*.list, un paquet par ligne, installés dans l'ordre des noms de fichiers ; 99-purge.list énumère ce qui est retiré ensuite.

• Les réglages du bureau

  rootfs/etc/dconf/db/moonlight.d/, au format keyfile de dconf. Ce sont des valeurs par défaut, pas des verrous : l'utilisateur peut toutes les changer.

• Reconstruire vite

  Après une modification de rootfs/ ou des listes de paquets, build.sh rootfs refait l'étape chroot sur la base en cache et build.sh image remballe l'ISO ; build.sh finish sert quand on travaille sur le menu de démarrage.

Obtenir de l'aide et signaler un bogue

Un rapport utile dit ce que vous attendiez, ce qui s'est passé à la place, et sur quel ordinateur. MoonLightOS se charge du troisième point :

• À propos de MoonLightOS → Copier le rapport place la version, le matériel, le moteur de rendu graphique et l'état de Secure Boot dans le presse-papiers, sous forme de texte.
• moonlight-selftest affiche les réglages de thème en vigueur, le bon chargement ou non de la feuille de style de l'interface, le pilote graphique actif et les services en échec.
• Pour un problème au démarrage, l'entrée Verbose boot écrit tous les messages à l'écran et sur le premier port série.
• Pour le programme d'installation, /var/log/moonlight-firstboot.log sur le système installé, et journalctl -b -p warning.

Où l'envoyer

Un suivi des anomalies public et un canal d'assistance seront annoncés ici. D'ici là, gardez votre rapport : tout ce qu'il doit contenir vient des deux outils ci-dessus.