{"id":27481482,"url":"https://github.com/systemd/particleos","last_synced_at":"2025-04-16T13:03:20.675Z","repository":{"id":212288785,"uuid":"699275439","full_name":"systemd/particleos","owner":"systemd","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-06T19:37:00.000Z","size":155,"stargazers_count":82,"open_issues_count":7,"forks_count":12,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-04-06T20:31:15.430Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/systemd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-02T09:59:36.000Z","updated_at":"2025-04-06T19:37:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"2143cc4c-4a42-42fb-8ad6-dedc56027139","html_url":"https://github.com/systemd/particleos","commit_stats":null,"previous_names":["systemd/particleos"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fparticleos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fparticleos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fparticleos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fparticleos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/systemd","download_url":"https://codeload.github.com/systemd/particleos/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249242956,"owners_count":21236584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-16T13:02:13.344Z","updated_at":"2025-04-16T13:03:20.668Z","avatar_url":"https://github.com/systemd.png","language":"Shell","readme":"# ParticleOS\n\nParticleOS is a fully customizable immutable distribution implementing the\nconcepts described in\n[Fitting Everything Together](https://0pointer.net/blog/fitting-everything-together.html).\n\nThe crucial difference that makes ParticleOS unique compared to other immutable\ndistributions is that users build the ParticleOS image themselves and sign it\nwith their own keys instead of installing vendor signed images. This allows\nconfiguring the image to your liking by having full control over which\ndistribution is used as the base and which packages are installed into the\nimage.\n\nThe ParticleOS image is built using [mkosi](https://github.com/systemd/mkosi).\n\nFirst, configure the variant you'd like to build in `mkosi.local.conf`. For a\ndesktop system, you'll want the `desktop` profile and either the `gnome` or the\n`kde` profile.\n\n```conf\n[Distribution]\nDistribution=arch\n\n[Config]\nProfiles=desktop,kde\n```\n\nTo build the image, run `mkosi -B -f` from the ParticleOS repository. Currently\nboth `arch` and `fedora` are supported distributions. Implementing support for a\nnew distribution (that's already supported in mkosi) is as simple as writing the\nnecessary config files to install the required packages for that distribution.\n\nTo update the system after installation, you clone the ParticleOS repository\nor your fork of it, make sure `mkosi.local.conf` is configured to your liking and\nrun `mkosi -B -ff sysupdate -- update --reboot` which will update the system using\n`systemd-sysupdate` and then reboot.\n\n## Using the OBS profile to fetch a newer systemd\n\nSometimes ParticleOS adopts systemd features as soon as they get merged into\nsystemd without waiting for an official release. That's why we recommend\nenabling the `obs` profile to enable the systemd repositories on OBS\n(https://software.opensuse.org//download.html?project=system%3Asystemd\u0026package=systemd)\ncontaining systemd packages which are built every day from systemd's git main\nbranch.\n\nTo enable the `obs` profile, add the following to `mkosi.local.conf`:\n\n```conf\n[Config]\nProfiles=obs\n```\n\n## Building systemd from source\n\nAs an alternative to using the `obs` profile, you can build systemd from source:\n\n```sh\ngit clone https://github.com/systemd/systemd\ncd systemd\nmkosi -f sandbox -- meson setup build\nmkosi -f sandbox -- meson compile -C build\nmkosi -t none -f\n```\n\nThen write the following to `mkosi.local.conf` in the ParticleOS repository to\nuse the artifacts from the systemd repository built by mkosi in ParticleOS:\n\n```conf\n[Content]\nVolatilePackageDirectories=../systemd/build/mkosi.builddir/\u003cdistribution\u003e~\u003crelease\u003e~\u003carch\u003e\n\n[Build]\nExtraSearchPaths=../systemd/build\n```\n\nMake sure the distribution and release in `mkosi.local.conf` are identical in the\nsystemd checkout and the particleos checkout.\n\nTo build a newer systemd, run `git pull` in the systemd repository followed by\n `mkosi -f sandbox -- meson compile -C build` and `mkosi -t none`.\n\n## Signing keys\n\nParticleOS images are signed for Secure Boot with the user's keys. To generate a new key,\nrun `mkosi genkey`. The key must be stored safely, it will be required to sign updates.\n\nThe key can be stored in a smartcard. Then you have to set the key in `mkosi.local.conf`:\n\n```\n[Validation]\nSecureBootKey=pkcs11:object=Private key 1;type=private\nSecureBootKeySource=provider:pkcs11\nSignExpectedPcrKey=pkcs11:object=Private key 1;type=private\nSignExpectedPcrKeySource=provider:pkcs11\nVerityKey=pkcs11:object=Private key 1;type=private\nVerityKeySource=provider:pkcs11\n```\n\n## Installation\n\nBefore installing ParticleOS, make sure that Secure Boot is in setup mode on the\ntarget system. The Secure Boot mode can be configured in the UEFI firmware\ninterface of the target system. If there's an existing Linux installation on the\ntarget system already, run `systemctl reboot --firmware-setup` to reboot into\nthe UEFI firmware interface. At the same time, make sure the UEFI firmware\ninterface is password protected so an attacker cannot just disable Secure Boot\nagain.\n\nTo install ParticleOS with a USB drive, first build the image on an existing\nLinux system as described above. Then, burn it to the USB drive with\n`mkosi burn /dev/\u003cusb\u003e`. Once burned to the USB drive, plug the USB drive into\nthe system onto which you'd like to install ParticleOS and boot into the USB\ndrive via the firmware. Then, boot into the \"Installer\" UKI profile. When you\nend up in the root shell, run\n`systemd-repart --dry-run=no --empty=force --defer-partitions=swap,root,home /dev/\u003cdrive\u003e`\nto install ParticleOS to the system's drive. Finally, reboot into the target\ndrive (not the USB) and the regular profile (not the installer one) to complete\nthe installation.\n\n## LUKS recovery key\n\nsystemd doesn't support adding a recovery key to a partition enrolled with a token\nonly (tpm/fido2). It is possible to use cryptenroll to add a recovery password\nto the root partition: `cryptsetup luksAddKey --token-type systemd-tpm2 /dev/\u003cid\u003e`\n\n## Firmwares\n\nOnly firmwares that are dependencies of a kernel module are included, but some\nmodules don't declare their dependencies properly. Dependencies of a module can be\nfound with `modinfo`. If you experience missing firmwares, you should report\nthis to the module maintainer. `FirmwareInclude=` can be added in `mkosi.local.conf`\nto include the firmware regardless of whether a module depends on it.\n\n## Configuring systemd-homed after installation\n\nAfter installing ParticleOS and logging into your systemd-homed managed user,\nrun the following to configure systemd-homed for the best experience:\n\n```sh\nhomectl update \\\n    --auto-resize-mode=off \\\n    --disk-size=max \\\n    --luks-discard=on \\\n    --luks-extra-mount-options \"user_subvol_rm_allowed,compress=zstd:1\"\n```\n\nDisabling the auto resize mode avoids slow system boot and shutdown. Enabling\nLUKS discard makes sure the home directory doesn't become inaccessible because\nsystemd-homed is unable to resize the home directory. The extra LUKS mount\noptions are BTRFS mount options to make image builds with `mkosi` faster by\ncompressing data on disk and allowing users to delete subvolumes.\n\n## Default root password and user when booting in a virtual machine\n\nIf you boot ParticleOS in a virtual machine using `mkosi vm`, the root password\nis automatically set to `particleos` and a default user `particleos` with password\n`particleos` is created as well.\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemd%2Fparticleos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystemd%2Fparticleos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemd%2Fparticleos/lists"}