Maple Linux Core – Build From Scratch

Building Maple Linux Core from Source

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.git
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:

  1. maple-calamares-branding – Installer customization
  2. maple-cinnamon-settings – Desktop theming and settings
  3. maple-lightdm-userlist – Login screen branding
  4. 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:

  1. Extracting the base Debian ISO (~3-5 minutes)
  2. Installing custom packages into the live filesystem
  3. Configuring Canadian defaults (locale, timezone, DNS)
  4. Adding additional software (LibreWolf, Krita, etc.)
  5. 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:

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

Using virt-manager (KVM/QEMU):

  1. Create new VM, select “Local install media”
  2. Choose your ISO file
  3. Allocate at least 4GB RAM and 25GB disk
  4. 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 (cross-platform, user-friendly)
  • Rufus (Windows)
  • Ventoy (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:

  1. Check the build log: build-YYYYMMDD-HHMMSS.log has detailed information
  2. Search existing issues: Codeberg Issues
  3. 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:

  1. Fork the repository on Codeberg
  2. Make your changes in a feature branch
  3. Test thoroughly (build ISO and test installation)
  4. 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

Happy Building! 🍁