{"id":13595605,"url":"https://github.com/r-darwish/alma","last_synced_at":"2025-04-09T13:32:46.657Z","repository":{"id":46103390,"uuid":"155720735","full_name":"r-darwish/alma","owner":"r-darwish","description":"Create Arch Linux based bootable USB drives","archived":true,"fork":false,"pushed_at":"2022-06-08T05:44:11.000Z","size":164,"stargazers_count":388,"open_issues_count":5,"forks_count":31,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-08-01T16:41:39.194Z","etag":null,"topics":["archlinux","archlinux-installer","linux","liveusb"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r-darwish.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}},"created_at":"2018-11-01T13:38:15.000Z","updated_at":"2024-07-27T23:08:38.000Z","dependencies_parsed_at":"2022-08-30T19:22:33.723Z","dependency_job_id":null,"html_url":"https://github.com/r-darwish/alma","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-darwish%2Falma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-darwish%2Falma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-darwish%2Falma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-darwish%2Falma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-darwish","download_url":"https://codeload.github.com/r-darwish/alma/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223394636,"owners_count":17138589,"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":["archlinux","archlinux-installer","linux","liveusb"],"created_at":"2024-08-01T16:01:53.399Z","updated_at":"2024-11-06T18:31:20.760Z","avatar_url":"https://github.com/r-darwish.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# ALMA - Arch Linux Mobile Appliance\n\n**Note**: This project is no longer maintained, and some people have reported that it made their host system unbootable. Use at your own risk.\n\nAlmost every live Linux distribution out there is meant for a specific purpose, whether it's data\nrescue, privacy, penetration testing or anything else. There are some more generic distributions\nbut all of them are based on squashfs, meaning that changes don't persist reboots.\n\nALMA is meant for those who wish to have a **mutable** live environment. It installs Arch\nLinux into a USB or an SD card, almost as if it was a hard drive. Some configuration is applied in\norder to minimize writes to the USB and making sure the system is bootable on both BIOS and UEFI\nsystems.\n\nUpgrading your packages is as easy as running `pacman -Syu` (or [Topgrade](https://github.com/r-darwish/topgrade/)) while the system is\nbooted. This tool also provides an easy chroot command, so you can keep your live environment up to\ndate without having to boot it. Encrypting the root partition is as easy as providing the `-e` flag\n\n## Installation\n\nYou can either build the project using cargo build or install the `alma` package from AUR.\n\n### Using Arch Linux derivatives\n\nUsing Arch Linux derivatives, such as Manjaro, isn't supported it ALMA. It may work and may not. Please do not open bugs or feature \nrequests if you are not using the official Arch Linux.\n\n## Usage\n\n### Image creation on removable device\n``` shell\nsudo alma create /dev/disk/by-id/usb-Generic_USB_Flash_Disk-0:0\n```\n\nThis will wipe the entire disk and create a bootable installation of Arch Linux. You can use either\nremovable devices or loop devices. As a precaution, ALMA will not wipe non-removable devices.\n\nNot specifying any path will cause ALMA to interactively prompt the user for a removable device.\n\n### Disk encryption\n\nYou can enable disk encryption with the `-e` flag:\n\n``` shell\nsudo alma create -e  /dev/disk/by-id/usb-Generic_USB_Flash_Disk-0:0\n```\n\nYou will be prompted to enter and confirm the encryption passphrase during image creation.\n\n### chroot\n\nAfter the installation is done you can either boot from it immediately or use `arch-chroot` to\nperform further customizations before your first boot (e.g. installing wireless device drivers).\n\nYou can run `arch-chroot` via ALMA:\n\n``` shell\nsudo alma chroot /dev/disk/by-id/usb-Generic_USB_Flash_Disk-0:0\n```\n\n### Create raw image and boot in qemu\n\nFor development and testing it may be useful to generate and boot the image in qemu.\n\nCreating a 10GiB raw image, with disk encryption:\n\n``` shell\nsudo alma create -e --image 10GiB almatest.img\n```\n\nIf you receive the following error:\n```\nError setting up a loop device: losetup: cannot find an unused loop device\n```\n\nCheck that you are running ALMA with sudo privileges, and reboot if you have installed a kernel update since your last reboot.\n\nMounting the raw image to a loop device:\n\n``` shell\nsudo losetup -f ./almatest.img\n```\n\nCheck loop device:\n``` shell\n sudo losetup -j ./almatest.img\n```\n```\n/dev/loop0: [2070]:6865917 (/path/to/image/almatest.img)\n```\nNote that your loop device number may differ.\n\nRun qemu via ALMA:\n``` shell\nsudo alma qemu /dev/loop0\n```\n\nThis will boot the image in qemu.\n\n## Presets\n\nReproducing a build can be easily done using a preset file.\n\nPreset files are simple TOML files which contain:\n* A list of packages to install: `packages = [\"mypackage\"]`\n* A post-installation script: `script = \"\"\" ... \"\"\"`\n* Environment variables required by the preset (e.g. used in the script): `enironment_variables = [\"USERNAME\"]`\n* A list of shared directories `shared_directories = [\"subdirectory\"]` - where subdirectory would be available at `/shared_dirs/subdirectory/` for use in the script of the preset.\n\nSee the presets directory for examples.\n\nPresets are used via the `--presets` argument (multiple preset files or directories may be provided):\n\n``` shell\nsudo ALMA_USER=archie alma create /dev/disk/by-id/usb-Generic_USB_Flash_Disk-0:0 --presets ./presets/user.toml ./presets/custom_preset.toml\n```\n\nPreset scripts are executed in the same order they are provided.\n\nIf a directory is provided, then all files and subdirectories in the directory are recursively crawled in alphanumeric order (all files must be ALMA .toml files). This allows you to use the following structure to compose many scripts in a specific order:\n\n```\n.\n├── 00-add_user.toml\n├── 01-xorg\n│   ├── 00-install.toml\n│   └── 01-config.toml\n└── 02-i3\n    ├── 00-install.toml\n    └── 01-copy_dotfiles.toml\n```\n\nExample preset TOML:\n\n``` toml\npackages = [\"sudo\"]\nscript = \"\"\"\nset -eux\nuseradd -m ${ALMA_USER}\npasswd ${ALMA_USER}\nusermod -G wheel -a ${ALMA_USER}\necho \"%wheel ALL=(ALL) ALL\" \u003e /etc/sudoers.d/wheel\n\"\"\"\nenvironment_variables = [\"ALMA_USER\"]\n```\n\nNote that shared directories in the preset scripts are mounted as bind mounts, so they are *not* mounted read-only. Any changes the custom script makes to the shared directory will be carried out in the preset shared directory of the host system, so be sure to copy (not move) files from the shared directories.\n\n### Order of execution\n\nALMA installs the packages and presets in the following order:\n\n1. All non-AUR packages are installed\n2. If AUR packages are present in the toml files, yay (or another\n   specified AUR helper) is installed\n3. All AUR packages are installed.\n4. Preset scripts are executed according to their filenames in\n   alphanumeric order.\n\nNote this may mean you have to workaround some package installations if\nthey depend on preset scripts.\n\nFor example, at the moment you cannot install Rust-based AUR packages in\nthe `aur_packages` array of the Preset TOMLs if you use rustup,\nsince rustup needs to be given the toolchain to\ninstall first. This can be worked around by carrying out the AUR\npackage installation inside the preset script itself in these cases.\n\n## Troubleshooting\n### mkinitcpio: /etc/mkinitcpio.d/linux.preset: No such file or directory\n\nEnsure you have both the `linux` and `base` packages installed. Note\nthat only Arch Linux is supported, not Arch Linux derivatives such as\nManjaro.\n\n### Problem opening /dev/... for reading! Error is 123.\n\nDelete all partitions on the disk first (e.g. with gparted) and try\nagain.\n\n## Similar projects\n\n* [NomadBSD](http://nomadbsd.org/)\n\n## Useful Resources\n\n* [Arch Wiki: Installing Arch Linux on a USB key](https://wiki.archlinux.org/index.php/Install_Arch_Linux_on_a_USB_key)\n* [ValleyCat's Arch Linux USB guide](http://valleycat.org/linux/arch-usb.html?i=1)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-darwish%2Falma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-darwish%2Falma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-darwish%2Falma/lists"}