# minios-live turns the linux-live scripts into a bootable MiniOS image

> minios-live is the build layer behind MiniOS, a portable Linux system with a graphical interface, packaging the linux-live scripts, submodules and modules into a bootable ISO and a Debian source package. The build is reproducible tarball work driven by a Makefile, and the documentation lives in a wiki rather than in the repository.

**minios-linux/minios-live** — These scripts build a bootable MiniOS ISO image.

- Repository: https://github.com/minios-linux/minios-live
- Stars: 845 · Forks: 66
- Language: Shell
- License: GPL-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/minios-linux-minios-live

## The build layer of a portable graphical Linux

MiniOS is described as a reliable, user friendly portable system with a graphical interface, and minios-live holds the scripts that build a bootable MiniOS ISO image. The repository is therefore the construction layer rather than the product itself, and the ISO that users download is the output of this build.

The base underneath is linux-live, and it is pulled in as a git submodule rather than vendored, with a submodules directory and a .gitmodules file at the root. Alongside it sit a set of module and package definitions, lokit.yaml, lokit.lock and lokit-terms.yaml, which is where the contents of the system are described. The repository also carries a minios-live script and a minios-cmd command, both of which are copied into the source package alongside the licence and the README.

The audience is two groups. The first is a user who wants to understand how the image is assembled, which is why the module definitions and the linux-live base are both visible. The second is a developer who wants to change the system, and the wiki explicitly covers both installation and configuration as well as how to extend the functionality with modules.

The licence is GPL-2.0, and the project's history is credited to a named group of contributors, from the original author and maintainer to the developer of the graphical interface and the developers of the PuppyRus Linux, ROSA Barium and PocketHandyBox systems that fed work into MiniOS.

## The Makefile builds a Debian package, not an ISO

The first thing to understand about this repository is what the Makefile actually does. Its targets are Debian packaging targets, not image targets, and the package name and version are derived from the changelog rather than hard coded:

```make
PACKAGE           := minios-live
VERSION           := $(shell dpkg-parsechangelog --show-field Version | sed "s/-[^-]*$$//")
BUILD_DIR         := build/$(PACKAGE)-$(VERSION)
SOURCE_DATE_EPOCH := $(shell dpkg-parsechangelog --show-field Timestamp)
```

The dependency check target is the first step and it fails the build when something is missing:

```make
check-deps:
	@echo "Checking build dependencies..."
	@if dpkg-checkbuilddeps; then \
		echo "All build-dependencies satisfied."; \
	else \
		echo "Install the missing build dependencies and run make again." >&2; \
		exit 1; \
	fi
```

After that, prepare-source assembles the source tree by copying the completions, docs, linux-live, manpages and po directories and the LICENSE, README.md, minios-cmd and minios-live files into the build directory. The orig target then creates the source tarball, and the tar invocation is what makes the output reproducible, with a fixed modification time taken from the changelog timestamp and a fixed numeric owner of zero:

```make
orig: prepare-source
	@echo "Creating reproducible orig tarball..."
	@tar --sort=name \
		--mtime="@$(SOURCE_DATE_EPOCH)" \
		--owner=0 --group=0 --numeric-owner \
		-cf - -C build $(PACKAGE)-$(VERSION) | \
		gzip -n > build/$(PACKAGE)_$(VERSION).orig.tar.gz
```

The final build-package target adds the debian directory and runs dpkg-buildpackage, and a lintian target checks the resulting changes file.

So the Makefile is a Debian release engineering tool. The ISO assembly itself happens elsewhere, in the linux-live scripts, and the wiki guide on building MiniOS is where that path is documented.

## Reproducibility is the reason the packaging is so fussy

Look again at those tar flags, because they encode a specific goal. The archive entries are sorted by name, the modification time of every file is set to the changelog timestamp, the owner and group are forced to zero, and gzip is told not to store the filename or the original timestamp. The result is that building the same source twice produces byte identical output.

That matters more here than in an ordinary package, because the Linux live build process itself is about producing an image that can be verified and reproduced by anyone with the same inputs. A live ISO is a single large artefact that people download and boot, and if two builds of the same commit differ, there is no way for a user to tell whether a difference in behaviour comes from the code or from the build environment.

The version string is also derived rather than declared. The changelog is the source of truth for the version, with the Debian revision suffix stripped off, and the same changelog supplies the timestamp used for the tarball. That means the changelog has to be edited before a build, and the build inherits whatever it says.

For a downstream packager this is convenient, because the rules are explicit and there is no hidden state. The cost is that the Debian toolchain is a hard requirement, since the version, the timestamp and the package build all come from dpkg tools rather than from a script written in the repository.

## Locales, completions and man pages ship with the system

The source tree carries the whole localisation apparatus, and it is a fair amount of it. There is a po directory of translation files, an update-po.sh script at the root, a completions directory for shell completion, and a manpages directory. The prepare-source target copies all of them into the build, which tells you they are part of the shipped package rather than build time extras.

The makepkg-style picture is that MiniOS is a live system where the user logs into a session and types, so translations, command completions and manual pages all matter to the end user experience. The two commands copied into the package, minios-live and minios-cmd, are the entry points a user or script would call.

The docs directory and the release-notes directory sit alongside them, and the images directory holds the artwork used by the website and the wiki.

A practical note for contributors: translations are updated through a script rather than by hand, so the workflow for changing a string is to edit the source, run update-po.sh, and commit the result. The wiki covers configuration and extension with modules, which is where the interaction between these directories is explained in detail.

## Modules are the unit of extension

The MiniOS wiki, as described in the README, covers how to extend the functionality with modules, and there is a dedicated guide for building MiniOS and modifying modules. The module definitions in lokit.yaml, lokit.lock and lokit-terms.yaml are the machine readable side of that system.

The three files have distinct jobs by name alone. The lock file is the resolved state, the yaml file is the declared state, and the terms file carries the terminology used across the system. The presence of a lock file means the set of modules is pinned, which is what makes a build reproducible and what lets a user roll back to a known configuration.

The distinction between a module and a package is worth keeping in mind when reading the repository. The Debian package built here is one artefact, the minios-live source package, and the modules it assembles are described by the lokit files and fetched or built according to those descriptions. So the dependency surface of an ISO build is much larger than the file list in this repository suggests.

That is also the honest limitation of this repository as a starting point. The code here is the build and packaging layer; the interesting decisions about what ends up on the ISO live in the module definitions, and the guide for changing them is in the wiki rather than in the README.

## Releases, cadence and where the documentation actually is

The release history is regular. v5.1.1 was tagged on 2026-01-07, v5.1.0 on 2025-11-29, and a v5.1.0 release candidate on 2025-11-22. The repository is not archived and the last push was on 2026-10-18, so work continues on the master branch well after the newest tag.

That gap between the last release and the last commit is the normal pattern for a repository that holds a build system rather than the shipped image. The ISO itself is published separately, and the official website at minios.dev is the place to find the edition list, the community forums and the direct download links for the images.

The documentation is split across three places, which is worth knowing before you start. The README is the entry point and points at the official website, the wiki and the Quick Start guide. The wiki holds the practical guides, covering installation, system configuration, customisation, extending the system with modules and the Building MiniOS guide. The repository itself has a docs directory, but it is not where the full documentation lives.

The licence is GPL-2.0. That is worth a moment's thought for anyone who wants to redistribute a modified MiniOS image, since the copyleft obligations attach to derivative works, and any specific question about how it applies belongs with your own counsel rather than with this page.

## Conclusion

minios-live suits anyone who wants to build MiniOS from source or to modify the modules that make up the system, since the linux-live base, the module set and the packaging recipe all live in this repository. It is the wrong starting point for a general purpose Linux build, because it is a build system for one specific distribution and the guidance on how to use the result is in the wiki, not the README. Before starting, read the Building MiniOS guide, check that dpkg-checkbuilddeps passes for the Debian packaging targets, and decide whether you need the ISO build path or only the module changes, because the Makefile here covers packaging rather than the image build itself.

## FAQ

### How do I build MiniOS from source with minios-live?

The README points to the Building MiniOS guide in the project wiki for the build and module modification details, and the Makefile in this repository covers the Debian packaging side, with a check-deps target that runs dpkg-checkbuilddeps and a build-package target that runs dpkg-buildpackage.

### What is linux-live and how does it relate to minios-live?

linux-live is the base that the MiniOS build scripts work on, and it is pulled into the repository as a git submodule. The prepare-source target copies the linux-live directory into the source tree alongside the completions, docs, manpages and po directories.

### How are MiniOS modules defined and changed?

The module configuration lives in lokit.yaml, lokit.lock and lokit-terms.yaml, and the wiki has a guide on building MiniOS and modifying modules. The lock file pins the resolved set, which is what keeps a build reproducible.

## Sources

- [Issues](https://github.com/minios-linux/minios-live/issues)
- [License: GPL-2.0](https://github.com/minios-linux/minios-live/blob/master/LICENSE)
- [minios-linux/minios-live on GitHub](https://github.com/minios-linux/minios-live)
- [README](https://github.com/minios-linux/minios-live/blob/master/README.md)
- [Releases](https://github.com/minios-linux/minios-live/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/minios-linux-minios-live