Getting Started

This page takes you through the whole path once: from nothing to a distro called My Distro booting in a virtual machine. It uses the template repository Eric-Ness/linuxlive-distro, so all you need is a GitHub account and a web browser. There's no Linux, Python or command line involved.

Allow about half an hour for an Ubuntu distro, most of it waiting for GitHub to build.

What you need

• A GitHub account (free).
• A wallpaper: a PNG of at least 1280×720 (1920×1080 is a good size) with one strong colour, such as green grass, blue sky or an orange sunset. See why the colour matters.
• A logo: a square PNG of exactly 128, 256 or 512 pixels. A transparent background looks best.
• To try the result: VirtualBox, or a USB stick of 8 GB or more that you don't mind erasing.

You can skip the art at first: the template comes with a placeholder wallpaper and logo.

1. Make your copy of the template

1. Open github.com/Eric-Ness/linuxlive-distro.
2. Click Use this template → Create a new repository.
3. Give it a name, for example my-distro. Keep it Public: builds are free in public repositories, and GitHub Free's storage for private ones is too small to hold an ISO.
4. Click Create repository.

GitHub may start building the unchanged example right away. You can let it run, or cancel it in the Actions tab.

Your new repository holds four things:

File	What it is
linuxlive.yaml	Your distro's spec
assets/wallpaper.png, assets/logo.png	Your art
.github/workflows/build.yml	A few lines that hand the build to linuxlive's reusable workflow
README.md	These steps, in short

2. Write the spec

Open linuxlive.yaml and click the pencil icon to edit it in the browser. Change it to what you want, for example:

schema_version: 1
name: My Distro
version: "0.1"
base: ubuntu
desktop: cinnamon
apps:
  - firefox
  - libreoffice
  - vlc
branding:
  wallpaper: assets/wallpaper.png
  logo: assets/logo.png
  accent_color: "#2e7d32"

Keep the quotes around "0.1" and "#2e7d32". Without them YAML reads the version as a number and treats everything after # as a comment, and the spec is rejected. Writing a Spec lists every option: base can be ubuntu or fedora, desktop can be gnome, kde or cinnamon, and there are 20 apps to choose from.

Click Commit changes. That starts a build, but you can add your art first: a new commit cancels a build that's still running.

3. Add your art

Open the assets folder, choose Add file → Upload files, and drop in your wallpaper.png and logo.png. They must keep exactly those names, so they replace the placeholders. Click Commit changes.

4. Watch it build

Open the Actions tab. The newest build run does the following in one job:

1. checks your spec, and stops with a clear message if something is wrong;
2. builds the system image and turns it into an ISO;
3. boots the ISO five ways in a virtual machine (UEFI and BIOS, USB stick and DVD, and once with Secure Boot on);
4. checks the booted system against your spec: its name, desktop, boot splash, apps and wallpaper.

It takes about 20 minutes for an Ubuntu distro and up to 40 for Fedora. When it's green, the run's summary says how many checks passed.

5. Download the ISO

Open the finished run and scroll to Artifacts. Download iso-my-distro, which is named after your distro's id. It's a zip with my-distro.iso and my-distro.iso.sha256 inside. Artifacts can only be downloaded while signed in to GitHub, and they're kept for 7 days. To get a fresh one later, choose Actions → build → Run workflow.

6. Try it

Unzip the download, check the checksum, and boot it in VirtualBox or from a USB stick. Testing and Booting has every step. The menu that appears first says Try My Distro 0.1. After a minute or so you should see your wallpaper, with Firefox, LibreOffice and VLC in the menu.

Changing it later

Edit the spec or replace the images and commit; every push to main builds again. Change version when you share a new build, so people can tell builds apart.

If something goes wrong

• "Check the spec" fails: the message names the problem, such as version: 0.1 is not of type 'string' (add the quotes) or an unknown app id.
• "Verify" fails on the wallpaper: the build checks that your wallpaper's colour shows on the desktop. Use a PNG with a stronger single colour, saved as an ordinary 8-bit PNG. See the image rules.
• Anything else: open the failing step's log. Then search the issues or open one, and link your run.

If you want to change linuxlive itself, or build on your own Linux machine, see Building with GitHub Actions (the fork route) and Building Locally.