{"id":24443637,"url":"https://github.com/endlessm/eos-installer","last_synced_at":"2025-04-12T21:27:46.921Z","repository":{"id":8616024,"uuid":"56624950","full_name":"endlessm/eos-installer","owner":"endlessm","description":"Installer UI which writes Endless OS disk images to disk","archived":false,"fork":false,"pushed_at":"2025-01-09T19:32:22.000Z","size":6590,"stargazers_count":20,"open_issues_count":0,"forks_count":7,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-03-26T15:42:58.575Z","etag":null,"topics":["endless-os","gnome","installer"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/endlessm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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}},"created_at":"2016-04-19T19:17:44.000Z","updated_at":"2024-08-20T23:00:09.000Z","dependencies_parsed_at":"2024-01-17T12:36:00.365Z","dependency_job_id":"7e26b275-3744-4793-9441-6843c1b1e177","html_url":"https://github.com/endlessm/eos-installer","commit_stats":null,"previous_names":[],"tags_count":446,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endlessm%2Feos-installer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endlessm%2Feos-installer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endlessm%2Feos-installer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endlessm%2Feos-installer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/endlessm","download_url":"https://codeload.github.com/endlessm/eos-installer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248633801,"owners_count":21136916,"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":["endless-os","gnome","installer"],"created_at":"2025-01-20T22:16:58.999Z","updated_at":"2025-04-12T21:27:46.900Z","avatar_url":"https://github.com/endlessm.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"Endless OS Reformatter\n======================\n\n![](./eos-installer-data/icons/hicolor/64x64/apps/com.endlessm.Installer.png)\n\nThis application is run from a live USB to write an Endless OS disk image to a\nfixed disk. It is branded as “Reformat with Endless OS” or “Reformat” to avoid\nconfusion with the [Endless Installer for Windows][rufus]. While primarily\ndesigned for Endless OS, it may be useful elsewhere — for example, [GNOME OS\nNightly](https://os.gnome.org/) ISOs use a modified version of `eos-installer` —\nand we welcome patches to make it more generic.\n\nThe codebase was originally derived from [`gnome-initial-setup`][gis], the\nfirst boot experience for GNOME (and Endless OS), and this is still visible in\nfile and symbol names, but the majority of the `gnome-initial-setup` code has\nbeen removed, leaving only the skeleton needed for this app.\n\nIt is typically launched by [our branch of\n`gnome-initial-setup`][endlessm-gis], though can be launched within a user\nsession as a normal app in some scenarios, as described below.\n\nUnlike a traditional installer, this application knows almost nothing about the\nOS being installed. It takes a disk image (possibly compressed) and either a GPG\nsignature or a SHA256 checksum, and writes the disk image to disk while\nverifying its GPG signature or checksum in parallel. The disk image is treated\nas just a stream of bytes, except in these respects:\n\n* The start of the image is examined to check that it has a [GUID Partition\n  Table](https://en.wikipedia.org/wiki/GUID_Partition_Table) with an [EFI\n  system partition](https://en.wikipedia.org/wiki/EFI_system_partition) and a\n  Linux root filesystem with flag 55 set, which is true of all Endless OS\n  (and GNOME OS) disk images.\n* The uncompressed size of the image is determined from the GPT to provide\n  accurate progress reporting and verify that the target drive is large enough.\n  While most supported compression formats (XZ, SquashFS) provide this\n  information, gzip only provides the uncompressed size modulo 2\u003csup\u003e32\u003c/sup\u003e,\n  and Endless OS disk images are typically (much!) larger than this threshold.\n* The first 1 MiB of the disk image is reserved, with zeros written to disk\n  instead. Once the rest of the image has been decompressed and written, if its\n  GPG signature or SHA256 checksum is valid, then the first 1MiB is written at the start of the\n  disk. This prevents booting into a partially-written or corrupt installation.\n\nApart from these details, you can essentially think of this app as a glorified\nGUI for `zcat | gpg --verify | dd`.\n\nThe GPG signature, if present, is verified against a keyring located at\n`/usr/share/keyrings/eos-image-keyring.gpg`. If both a GPG signature and SHA256\nchecksum are present, the GPG signature is preferred.\n\n[rufus]: https://github.com/endlessm/rufus\n[gis]: https://gitlab.gnome.org/gnome/gnome-initial-setup\n[endlessm-gis]: https://github.com/endlessm/gnome-initial-setup\n\n\nInstalling from Live Image\n--------------------------\n\nWhen booted into an Endless OS live system, eos-installer can be used to write\na copy of the running (but unmodified) OS image to permanent storage.  To allow\nthis, eos-installer is shipped as part of the normal Endless OS ostree, but is\nhidden from the end user unless the OS is booted in live mode.\n\nDuring the `gnome-initial-setup` flow, the user is offered the choice to try a\nlive session, or run the reformatter immediately. If they choose the former,\nthis application can be launched as a normal app from the live session.\n\nThere are two disk layouts for live systems:\n\n1. A large exFAT partition with label `eoslive`, which contains an uncompressed\n   Endless OS image file and associated signature, next to the normal EFI and\n   BIOS boot partitions. We sometimes refer to this layout as a *combined live\n   \u0026 installer USB*. It's created using [`eos-write-live-image`][ewli]. \n2. An ISO image, produced by [eos-image-builder][eib] as part of the OS build\n   process. Ignoring the bootloader stuff, this is an ISO9660 filesystem which\n   contains a SquashFS disk image containing an Endless OS disk image, and\n   signatures or checksums for both the uncompressed disk image and the SquashFS image\n   alongside it.\n\nThese are both treated very similarly by `eos-installer`. Once it has located\nthe partition containing the GPG signature for the uncompressed image, it reads\nthe disk image itself from the read-only device-mapper device that the system\nis booted from. This avoids `eos-installer` needing to know how to extract a\nfile from a SquashFS image. It's also convenient during development because you\ncan basically ignore the SquashFS case.\n\nBecause the `eos-installer` application is run from *within the disk image\nbeing installed*, this configuration is quite hard to test during development:\nreplacing the `eos-installer` binary modifies the disk image and so invalidates\nits GPG signature.\n\n[ewli]: https://github.com/endlessm/eos-meta/blob/master/eos-tech-support/eos-write-live-image\n[eib]: http://github.com/endlessm/eos-image-builder\n\n\nInstalling with Standalone Image\n--------------------------------\n\nWe also publish an `eosinstaller` ostree \u0026 OS image. This is a cut-down build\nof the OS which excludes almost all the normal applications: it can only be\nused to run eos-installer (this application) from the `gnome-initial-setup`\ngreeter session.\n\n[`eos-write-installer`][ewi] writes an `eosinstaller` disk image plus an OS\nimage to be installed to removable media. The resulting partition layout is:\n\n- EFI and BIOS boot partitions\n- a small ext4 partition containing the `eosinstaller` OS deployment\n- an exFAT partition with label `eosimages`, occupying the rest of the device\n  containing the OS image to be installed and its corresponding signature or checksum\n  \nOne can copy additional OS images and their corresponding signatures or checksums to the\nexFAT partition, and they'll be offered as extra choices by `eos-installer`.\n\nThis mode is less useful to end users – you can't try the OS you're about to\ninstall – but it is an easier setup to replicate during development. (In fact,\n`eos-installer` doesn't check that the `eosimages` partition is on the same\nphysical device that it's running from.)\n\nThis is the only mode which supports [unattended installation](./UNATTENDED.md).\n\n[ewi]: https://github.com/endlessm/eos-meta/blob/master/eos-tech-support/eos-write-installer\n\nDevelopment\n-----------\n\nOne way to run this application while developing it is with the following setup:\n\n* Host system: a normal Endless OS installation. Build `eos-installer` in\n  `toolbox`, and run it on the host system.\n* Disk 1: a GPT-formatted drive with an exFAT partition with label `eosimages`.\n  As shown below, this can be a loopback device if you want to avoid using\n  removable media, but it has to have a GPT.  This partition should contain, in\n  its root directory:\n  - a GPT disk image (`.img`, `.img.xz` or\n    `.img.gz`). `xz` decompression is *really* slow, so `gz` is strongly\n    recommended.\n  - either a corresponding `.img(.[gx]z)?.asc` GPG\n  signature, or a corresponding `.img(.[gx]z)?.sha256` SHA-256 checksum.\n* Disk 2: a target disk or loop associated file large enough to write the OS\n  image to. `eos-installer` only considers non-removable disks with a\n  corresponding block device to be install targets, so unless you have a\n  computer with multiple built-in disks, you'll need to either do all this in a\n  virtual machine with multiple fixed disks, or use a loopback device.\n\nTo use loop devices for testing, the following procedure can be used:\n\n```\n# Create a source disk image to store the images to be installed\ntruncate -s 5G src.img\n# Write a GPT partition table with a single Linux partition\nsfdisk src.img \u003c\u003c\"EOF\"\nlabel: gpt\ntype=L\nEOF\n# Attach a loop device with partition scanning to the source image\nsrc_loop=$(sudo losetup -P --show -f src.img)\n# Make an exFAT file system on the first partition with the eosimages label\nsudo mkfs.exfat -n eosimages \"${src_loop}p1\"\n# Mount it and copy the to be installed image files to it\nsudo mount -t exfat -o \"uid=$(id -u),gid=$(id -g)\" \"${src_loop}p1\" /mnt\ncp eos*.img.* /mnt\n# Create a target disk image to install to\ntruncate -s 5G tgt.img\n# Attach a loop device with partition scanning to the target image\ntgt_loop=$(sudo losetup -P --show -f tgt.img)\n```\n\nNow `eos-installer` can be run. To cleanup, unmount the source image and detach\nthe loop devices:\n\n```\nsudo umount /mnt\nsudo losetup -d \"$src_loop\"\nsudo losetup -d \"$tgt_loop\"\n```\n\nIf you do not have an `eosimages` partition with at least one image file on it,\nrunning the app will take you straight to the error screen.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fendlessm%2Feos-installer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fendlessm%2Feos-installer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fendlessm%2Feos-installer/lists"}