Maple Linux Core - Build From Scratch

This guide will walk you through building your own Maple Linux Core ISO from the Codeberg repository.

What You’ll Need

Hardware Requirements

Operating System: Debian 13 “Trixie” or Ubuntu 24.04+ (or derivatives)
Disk Space: At least 10GB free space for build files and ISO
Memory: 4GB RAM minimum (8GB recommended for faster builds)
Internet: To download base ISO and packages

Knowledge Requirements

Basic command line comfort (cd, ls, sudo)
Understanding of how to run shell scripts
Patience for a 20-30 minute build process

Step 1: Install Build Dependencies

Open a terminal and install the required packages:

sudo apt-get update
sudo apt-get install -y \
    squashfs-tools \
    xorriso \
    isolinux \
    syslinux-utils \
    dpkg-dev \
    debhelper \
    imagemagick \
    git \
    wget

What these do:

squashfs-tools & xorriso: Extract and rebuild ISO files
isolinux & syslinux-utils: Handle boot configuration
dpkg-dev & debhelper: Build Debian packages
imagemagick: Generate graphical assets during package builds
git: Clone the repository
wget: Download the base Debian ISO

Step 2: Clone the Repository

cd ~
git clone https://codeberg.org/maplelinux/maple-linux-core-v1.git maple-linux-core
cd maple-linux-core

This creates a maple-linux-core directory in your home folder with all the source code.

Step 3: Download the Base Debian ISO

Maple Linux Core is built by remastering an official Debian Live ISO. Download it:

wget https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/debian-live-13.0.0-amd64-cinnamon.iso

Note: This is about 3GB, so it may take a few minutes depending on your connection.

Important: Keep the ISO in the maple-linux-core directory (where you cloned the repo).

Step 4: Build the Custom Packages

Maple Linux Core’s customizations are implemented as four Debian packages. Build them all:

cd packages
./build_all_packages.sh

What’s happening: This script builds each package in sequence:

maple-calamares-branding - Installer customization
maple-cinnamon-settings - Desktop theming and settings
maple-lightdm-userlist - Login screen branding
maple-grub-text - Boot menu text customization

You’ll see output for each package as it builds. The process takes about 2-5 minutes total.

Success looks like:

Building maple-calamares-branding...
✓ Package built: maple-calamares-branding_1.0-1_all.deb

Building maple-cinnamon-settings...
✓ Package built: maple-cinnamon-settings_1.0-1_all.deb

Building maple-lightdm-userlist...
✓ Package built: maple-lightdm-userlist_1.0-1_all.deb

Building maple-grub-text...
✓ Package built: maple-grub-text_1.0-1_all.deb

All packages built successfully!

Troubleshooting: If any package fails to build, check that all dependencies from Step 1 are installed.

Step 5: Build the ISO

Now for the main event! This will take 15-25 minutes depending on your system.

cd ..  # Go back to maple-linux-core directory
sudo ./build_debian_remaster.sh debian-live-13.0.0-amd64-cinnamon.iso

Why sudo?: The script needs root privileges to mount filesystems and modify system files in the ISO.

What’s happening:

Extracting the base Debian ISO (~3-5 minutes)
Installing custom packages into the live filesystem
Configuring Canadian defaults (locale, timezone, DNS)
Adding additional software (LibreWolf, Krita, etc.)
Rebuilding the ISO with all customizations (~5-10 minutes)

Success looks like:

[... lots of output ...]

ISO build complete!
Output: maple-linux-core-1.0-amd64.iso
Size: ~3.2GB

Build log: build-YYYYMMDD-HHMMSS.log

Step 6: Test Your ISO

Your freshly built ISO is now ready! It’s named maple-linux-core-1.0-amd64.iso in the maple-linux-core directory.

Option A: Test in a Virtual Machine (Recommended)

Using VirtualBox:

Create a new VM with at least 4GB RAM and 25GB disk
Set the ISO as the optical drive
Boot and test

Using virt-manager (KVM/QEMU):

Create new VM, select “Local install media”
Choose your ISO file
Allocate at least 4GB RAM and 25GB disk
Boot and test

Option B: Create a Bootable USB

On Linux:

# Replace /dev/sdX with your USB device (check with 'lsblk')
# WARNING: This will erase everything on the USB drive!
sudo dd if=maple-linux-core-1.0-amd64.iso of=/dev/sdX bs=4M status=progress
sudo sync

On Windows/Mac: Use tools like:

Etcher (opens in a new tab) (cross-platform, user-friendly)
Rufus (opens in a new tab) (Windows)
Ventoy (opens in a new tab) (can hold multiple ISOs)

Understanding the Build System

Directory Structure

maple-linux-core/
├── packages/                          # Custom Debian packages
│   ├── maple-calamares-branding/     # Installer branding
│   ├── maple-cinnamon-settings/      # Desktop settings
│   ├── maple-lightdm-userlist/       # Login screen theme
│   ├── maple-grub-text/              # Boot menu branding
│   └── build_all_packages.sh         # Builds all packages
├── build_debian_remaster.sh          # Main ISO build script
├── debian-live-13.0.0-amd64-cinnamon.iso  # Base Debian ISO (you download this)
└── maple-linux-core-1.0-amd64.iso          # Your final ISO (created by build)

Build Logs

Every ISO build creates a timestamped log file: build-YYYYMMDD-HHMMSS.log

If something goes wrong, this log contains detailed information about what happened.

Cleanup Between Builds

If you need to rebuild or something went wrong:

# Remove build artifacts
sudo rm -rf work/
sudo rm -rf iso-extract/
rm -f maple-linux-core-*.iso
rm -f build-*.log

# You'll need to rebuild packages if you changed them
cd packages
rm -f *.deb
./build_all_packages.sh
cd ..

Customizing Your Build

Want to make changes? Here’s where to look:

Change Desktop Wallpaper

Edit: packages/maple-cinnamon-settings/assets/wallpaper.jpg Then rebuild packages and ISO.

Modify Installer Branding

Edit files in: packages/maple-calamares-branding/ Then rebuild packages and ISO.

Add/Remove Software

Edit: build_debian_remaster.sh Look for the section that installs additional packages (around line 150-200)

Change Default Settings

Edit: packages/maple-cinnamon-settings/etc/skel/.config/ These files become the defaults for new users.

After any changes:

cd packages
./build_all_packages.sh  # Rebuild packages
cd ..
sudo ./build_debian_remaster.sh debian-live-13.0.0-amd64-cinnamon.iso  # Rebuild ISO

Troubleshooting

“No space left on device”

The build needs ~10GB free space
Check with: df -h .
Clean up: sudo rm -rf work/ iso-extract/

“Package build failed”

Make sure all dependencies are installed (Step 1)
Check individual package directories for specific errors
Look at the error message—usually it’s a missing tool

“ISO won’t boot in VM”

Ensure VM has UEFI support enabled (or disabled, try both)
Allocate at least 2GB RAM (4GB recommended)
Verify the ISO isn’t corrupted: md5sum maple-linux-core-1.0-amd64.iso

“Changes didn’t appear in final ISO”

Did you rebuild the packages? (cd packages && ./build_all_packages.sh)
Check the build log for errors
Some changes require clearing the work directory first

“Permission denied” errors

The main build script needs sudo: sudo ./build_debian_remaster.sh ...
Don’t run package builds with sudo: ./build_all_packages.sh (no sudo)

Advanced: Building on Other Distributions

While officially supported on Debian/Ubuntu, you can build on other distributions:

Fedora/RHEL:

sudo dnf install squashfs-tools xorriso syslinux dpkg-dev ImageMagick git wget

Arch Linux:

sudo pacman -S squashfs-tools libisoburn syslinux dpkg imagemagick git wget

Note: Package names may vary. The build process is the same after dependencies are installed.

Getting Help

If you run into issues:

Check the build log: build-YYYYMMDD-HHMMSS.log has detailed information
Search existing issues: Codeberg Issues (opens in a new tab)
Open a new issue: Include:
- Your build environment (OS, version)
- Full error message
- Relevant portions of build log
- Steps to reproduce

Next Steps

Now that you have a working build environment:

Experiment with customizations
Contribute improvements back to the project
Create your own derivative distribution
Help improve documentation

Contributing Your Changes

If you make improvements you’d like to share:

Fork the repository on Codeberg
Make your changes in a feature branch
Test thoroughly (build ISO and test installation)
Open a pull request with:
- Clear description of what changed
- Why the change is beneficial
- Any testing you’ve done

We welcome contributions that align with the project’s minimalist philosophy!

Questions? Open an issue on Codeberg (opens in a new tab)

Happy Building! 🍁