{"id":15628426,"url":"https://github.com/clayrisser/linux-factory","last_synced_at":"2025-09-12T20:42:37.600Z","repository":{"id":91235248,"uuid":"65759229","full_name":"clayrisser/linux-factory","owner":"clayrisser","description":"a framework used to create custom debian linux operating systems","archived":false,"fork":false,"pushed_at":"2024-01-30T04:42:11.000Z","size":12236,"stargazers_count":299,"open_issues_count":1,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-09-10T19:20:17.896Z","etag":null,"topics":["debian","developer-tools","linux","live-build","operating-system"],"latest_commit_sha":null,"homepage":"https://gitlab.com/risserlabs/community/linux-factory","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clayrisser.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}},"created_at":"2016-08-15T19:34:59.000Z","updated_at":"2025-06-01T01:56:38.000Z","dependencies_parsed_at":"2023-06-04T12:15:30.131Z","dependency_job_id":"3d7730f3-c5f2-4f6d-939b-ea44ec3ad48d","html_url":"https://github.com/clayrisser/linux-factory","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/clayrisser/linux-factory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clayrisser%2Flinux-factory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clayrisser%2Flinux-factory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clayrisser%2Flinux-factory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clayrisser%2Flinux-factory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clayrisser","download_url":"https://codeload.github.com/clayrisser/linux-factory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clayrisser%2Flinux-factory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274873613,"owners_count":25365824,"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","status":"online","status_checked_at":"2025-09-12T02:00:09.324Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["debian","developer-tools","linux","live-build","operating-system"],"created_at":"2024-10-03T10:22:33.567Z","updated_at":"2025-09-12T20:42:37.582Z","avatar_url":"https://github.com/clayrisser.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐧🏭 linux-factory\n\n\u003e a framework used to create custom linux debian operating systems\n\n![](assets/linux-factory.jpeg)\n\n## Cloud\n\nYou can build and test this system in the cloud using gitlab-runner and virtualbox. You must use a\ncloud server that supports virtualization. DigitalOcean is recommended because it has been tested on it\nand it supports virtualization.\n\nRun the following script to install gitlab-runner, sway with a vnc server, and virtualbox.\n\n```sh\nwget -qO- https://gitlab.com/bitspur/community/linux-factory/-/raw/main/scripts/cloud-setup.sh | sudo sh\n```\n\nConnect with a vnc client at \u003cIP_ADDRESS\u003e:5900\n\nThe window manager is running sway. You can access a cheatsheet for sway commands at the link below.\n\n[Sway Cheatsheet](https://depau.github.io/sway-cheatsheet)\n\nFor example `WIN-d` will open the dmenu to start programs and `WIN-ENTER` will open a terminal.\n\n## Usage\n\n### Building\n\nEdit configurations in the `os/config.yaml`, activate custom overlays and when ready . . .\n\n```\nmake build\n```\n\nOnce the build has completed, you can find the iso installer located in the `.build/lb` folder.\n\n### Reset Environment\n\nRun the following command to completely reset your environment.\n\n```sh\nsudo git clean -fxd\n```\n\n\u003e Please note that if you stopped the build in the middle of execution (for example `CTRL-C`),\n\u003e it's possible you will get a permission error. If this happens you may need to restart your\n\u003e computer and try resetting after you have rebooted.\n\n## Dependencies\n\nThis system can only be built from a Debian based operating system. While\nany Debian based operating system should work, this is only tested against\nthe official Debian distribution on amd64.\n\nYou can install all of the dependencies with the following command.\n\n```sh\nsudo apt-get install -y imagemagick make git git-lfs grub-emu live-build python3-minimal jq python3-poetry-core python3-venv yq\n```\n\n### Required\n\n| Name        | Install                                                 | Url                                                                           |\n| ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| GNU Make    | `sudo apt-get install -y make`                          | https://www.gnu.org/software/make                                             |\n| Git         | `sudo apt-get install -y git`                           | https://git-scm.com                                                           |\n| Git LFS     | `sudo apt-get install -y git-lfs`                       | https://git-lfs.com                                                           |\n| ImageMagick | `sudo apt-get install -y imagemagick`                   | https://imagemagick.org                                                       |\n| Live Build  | `sudo apt-get install -y live-build`                    | https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html |\n| Python 3    | `sudo apt-get install -y python3-minimal`                       | https://www.python.org                                                        |\n| jq          | `sudo apt-get install -y jq`                            | https://stedolan.github.io/jq                                                 |\n| poetry      | `sudo pip3 install poetry --break-system-packages`      | https://python-poetry.org                                                     |\n| virtualenv  | `sudo apt-get install -y python3-venv`                  | https://virtualenv.pypa.io                                                    |\n| yq          | `sudo apt-get install -y yq` | https://mikefarah.gitbook.io/yq                                               |\n\n### Optional\n\n| Name          | Install                            | Url                                                             |\n| ------------- | ---------------------------------- | --------------------------------------------------------------- |\n| Grub Emulator | `sudo apt-get install -y grub-emu` | https://manpages.debian.org/testing/grub-emu/grub-emu.1.en.html |\n\n## Overlays\n\nOverlays are configurable, flexible and decoupled customizations that get applied to the operating system build. They\ncan be mixed and matched with other overlays, or be completely disabled if you don't want those changes.\n\nOverlays get _\"overlayed\"_ on top of the `os` directory during the build. This means the file structure inside\nof an overlay and the file structure of the `os` directory are identical.\n\n### Example\n\nThe example overlay showcases the capabilities of an overlay. You can use it as a\nstarting point for one of your overlays, or simply use it as a reference.\n\n[overlays/example](overlays/example)\n\n### Debian Installer\n\nThe Debian Installer is the official installation system for the Debian operating system.\nIt provides a user-friendly interface for installing Debian on a wide range of hardware,\nfrom desktops and laptops to servers and embedded systems. The Debian Installer supports\nmultiple languages, network installations, and a variety of disk partitioning options. With\nits flexible and customizable design, the Debian Installer is a popular choice for many\nusers who are looking to install Debian on their systems.\n\n[overlays/debianInstaller](overlays/debianInstaller)\n\n### Grub\n\nGRUB (GRand Unified Bootloader) is a boot loader package from the GNU Project. It is used to\nboot Linux operating systems, as well as a number of other operating systems. In the context\nof this system, Grub can be used as an overlay to customize the boot loader.\n\n[overlays/debianInstaller](overlays/debianInstaller)\n\n### Sway\n\nSway is a tiling window manager for Wayland. It provides a tiling window manager\nexperience for users who are looking for a modern, keyboard-driven interface. In the\ncontext of this system, Sway can be used as an overlay to provide a tiling\nwindow manager for the target system.\n\n[overlays/sway](overlays/sway)\n\n## Overlay Components\n\n### Fonts\n\nSupports `zip`, `tar` and `tar.gz` files that contain `.ttf` or `.otf` fonts\n\n### Packages\n\n### Repos\n\n### Filesystem\n\n### Prompt\n\n#### Types\n\n- `string`\n- `boolean`\n- `select`\n- `multiselect`\n- `error`\n- `note`\n- `password`\n\n### Hooks\n\nTo use the hooks in your overlay, you will need to create a file named overlay.py within your overlay directory. This file should contain a class named OverlayHooks that implements methods for each hook.\n\nEach hook has two corresponding methods, one for before the stage is executed and one for after the stage is executed. There are currently three stages in the process: build, config, and prepare. This means the following hooks are available for you to use:\n\n- `before_build()`\n- `after_build()`\n- `before_config()`\n- `after_config()`\n- `before_prepare()`\n- `after_prepare()`\n\nFor example, if you wanted to run some custom code before the build stage is executed, you could implement the following in your overlay.py file:\n\n_overlay.py_\n\n```py\nclass OverlayHooks:\n    def before_build(self):\n        # Your custom code here\n```\n\nIt's important to note that the order in which hooks are executed is determined by the order in which the overlays are specified. Make sure to take this into consideration when implementing your hooks.\n\n### Script Hooks\n\n\u003e Script hooks are a linux-factory concept and should not be confused with the live build hooks available at `lb/hooks/`.\n\nDuring the installation process, there are two script hooks that can be utilized, `post-install` and `user-post-install`.\n\n#### Location of Script Hooks\n\nScript hooks should be placed in the `hooks/\u003chook\u003e` folder. All scripts within the specified\nfolder will be executed during the corresponding hook.\n\n\u003e the name of the script should be the same name as your overlay to prevent collisions with hooks from other overlays\n\n#### Execution of Script Hooks\n\n- `user-post-install`: This script hook will execute after the system has been installed as the newly created user.\n- `post-install`: This script hook will also execute after the system has been installed, but it runs as the root user.\n\n#### Example\n\nHere's an example of how you can utilize the user-post-install script hook.\n\nCreate a folder named user-post-install in the hooks directory and add a file named script.sh in it. In the script.sh file, you can add the following code.\n\n_hooks/user-post-install/\\\u003coverlay\\\u003e.sh_\n\n```sh\n#!/bin/sh\n\necho \"Running user-post-install script\"\n```\n\n## Live Build Cheatsheet\n\n### Definitions\n\n- **live medium** - the ISO image and filesystem\n- **live system** - the operating system booted from the live medium\n- **installed system** - the operating system installed from debian installer\n- **chroot stage** - stage when building the image\n- **binary stage** - stage when building the live medium (binary can also refer to the debian installer)\n\n### File Structure\n\n- `config/archives/*.{list,key}.binary` - repositories added to _live system_ `/etc/apt/sources.list.d/`\n- `config/archives/*.{list,key}.chroot` - repositories loaded during the _chroot stage_\n- `config/includes.binary/*` - files to include in the _live medium's_ filesystem\n- `config/includes.chroot/*` - files to include in the _live system's_ filesystem\n- `config/includes.installer/*` - configuration for debian installer\n- `config/package-lists/*.list.binary` - packages to place in the APT `pool/` repository on the _live medium_ (for offline packages)\n- `config/package-lists/*.list.chroot_install` - packages to install in the _live system_ and _installed system_\n- `config/package-lists/*.list.chroot_live` - packages to install in the _live system_ only (works by uninstalling them from _installed system_)\n- `config/package-lists/*.list.chroot` - packages to install in the _live system_ (which will most likely be added to the _installed system_)\n- `config/packages.binary` - udeb packages to install for the debian installer\n- `config/packages.chroot` - deb packages to install for the live system\n\n_I'm not sure exactly what the differences between `config/package-lists/*.list.chroot` and\n`config/package-lists/*.list.chroot_install` are._\n\n\u003e WARNING: _binary_ unfortunately has many different meanings in the documentation depending on the context. The following table helps clarify the context of binary.\n\n| binary                                | refers to             |\n| ------------------------------------- | --------------------- |\n| `config/archives/*.{list,key}.binary` | _live system_         |\n| `config/includes.binary/*`            | _live medium_         |\n| `config/package-lists/*.list.binary`  | _live medium_ `/pool` |\n| `config/packages.binary`              | _debian installer_    |\n\n\u003e WARNING: `config/archives/*.{list,key}.chroot` does not make the repositories available to the _live system_. Instead you must use `config/archives/*.{list,key}.binary` for the repositories to be available to the _live system_.\n\n### Mounts\n\n- **live medium** - `/cdrom` if debian installer or `/run/live/medium` from live system\n- **installed system** - `/target` if debian installer or `/tmp/calamares-root-*` if calamares\n\n## Resources\n\n- https://bugs.launchpad.net/subiquity/+bug/1960068\n- https://debian-live-config.readthedocs.io/en/latest/custom.html\n- https://discourse.ubuntu.com/t/automated-server-install-reference/16613/21\n- https://github.com/elementary/os/wiki/Building-ISO-Images\n- https://groups.google.com/g/linux.debian.user/c/yN-MAMle-qE?pli=1\n- https://help.ubuntu.com/community/InstallCDCustomization\n- https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html\n- https://manpages.debian.org/unstable/live-build/lb_config.1.en.html\n- https://wiki.debian.org/DebianInstaller/NetbootFirmware\n- https://www.debian.org/releases/stable/i386/ch06s04.en.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclayrisser%2Flinux-factory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclayrisser%2Flinux-factory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclayrisser%2Flinux-factory/lists"}