Creating Custom Arch Linux ISO Images with Local Repository Support

Creating a custom Arch Linux ISO image allows you to build a personalized live environment with pre-configured software, local repositories, and automated installation capabilities. This guide covers the complete process from initial setup to building production-ready ISO images with CI/CD integration.

What You’ll Learn

This document provides comprehensive instructions for creating custom Arch Linux ISO images that include live boot capabilities, local package repositories for offline installation, custom environment configurations, and automated build pipelines. You’ll learn to use archiso effectively and integrate advanced features like the Calamares installer.

Prerequisites

Before starting, ensure you have:

An Arch Linux system with administrative privileges
Basic understanding of Arch Linux package management
Familiarity with shell scripting and system administration
At least 4GB of available disk space for the build process
Understanding of GPG key management for package signing

Core Components Overview

Archiso Framework

Archiso is Arch Linux’s official tool for creating live ISO images. It provides:

Live boot environment creation
Package installation and configuration
Custom filesystem modifications
Automated build processes

Essential Elements

A custom Arch Linux ISO typically includes:

Live Environment: Bootable system with pre-installed software
Local Repository: Offline package access for installations
Installation Tools: Automated or guided installation processes
Custom Configurations: Pre-configured user environments and settings

Project Structure and Planning

Recommended Directory Layout

custom-arch-iso/
├── archiso-profile/
│   ├── airootfs/
│   ├── efiboot/
│   ├── isolinux/
│   ├── packages.x86_64
│   └── profiledef.sh
├── local-repo/
│   ├── packages/
│   └── repo-db/
├── build-scripts/
└── ci-config/

Build Environment Setup

Create a dedicated build environment:

# Create build directory structure
mkdir -p ~/custom-arch-iso/{work,output,profile}
 
# Set up temporary filesystem for faster builds
sudo mount -t tmpfs -o size=4G tmpfs ~/custom-arch-iso/work

Setting Up the Build Environment

Installing Required Packages

Install archiso and essential build tools using pacman package management:

# Install archiso and related tools
sudo pacman -S archiso git
 
# Optional: Install additional build tools
sudo pacman -S devtools pacman-contrib

Copying Base Profile

# Copy the default releng profile as starting point
cp -r /usr/share/archiso/configs/releng/ ~/custom-arch-iso/profile/
 
# Navigate to profile directory
cd ~/custom-arch-iso/profile/

Integrating Local Package Repository

Repository Structure

A local repository enables offline package installation and custom software distribution. The custom repository creation guide provides detailed instructions for building and maintaining package repositories.

# Create repository directory
mkdir -p ~/custom-arch-iso/local-repo
 
# Add custom packages to repository
repo-add ~/custom-arch-iso/local-repo/custom.db.tar.xz ~/custom-arch-iso/local-repo/*.pkg.tar.xz

GPG Key Management

For package signing and verification, you’ll need properly configured GPG keys for signing and verification:

# Generate or import GPG keys for package signing
gpg --gen-key
 
# Export public key for inclusion in ISO
gpg --export --armor your-key-id > custom-keyring.asc

The GPG operations cheatsheet provides comprehensive guidance on key generation, trust management, and signature verification essential for secure package repositories.

Repository Integration

Add the local repository to the ISO build process:

Modify pacman configuration:

# Edit airootfs/etc/pacman.conf
cat >> airootfs/etc/pacman.conf << 'EOF'
[custom]
SigLevel = Optional TrustAll
Server = file:///repo/custom
EOF

Include repository in ISO:

# Copy repository to airootfs
mkdir -p airootfs/repo/custom
cp -r ~/custom-arch-iso/local-repo/* airootfs/repo/custom/

Customizing the Live Environment

Package Selection

Edit packages.x86_64 to include desired packages. For comprehensive package management operations, see the pacman commands reference:

# Base system
base
linux
linux-firmware

# Development tools
base-devel
git
vim

# Custom packages
your-custom-package

System Configuration

Modify files in airootfs/ to customize the live environment:

Root filesystem modifications:

# Create custom user
echo "customuser:x:1000:1000:Custom User:/home/customuser:/bin/bash" >> airootfs/etc/passwd
 
# Add sudoers configuration
echo "customuser ALL=(ALL) NOPASSWD: ALL" >> airootfs/etc/sudoers.d/customuser

Network configuration:

# Enable NetworkManager
ln -sf /usr/lib/systemd/system/NetworkManager.service \
    airootfs/etc/systemd/system/multi-user.target.wants/

Custom Scripts and Hooks

Add initialization scripts:

# Create custom startup script
cat > airootfs/usr/local/bin/custom-init.sh << 'EOF'
#!/bin/bash
# Custom initialization commands
systemctl enable NetworkManager
systemctl start NetworkManager
EOF
 
chmod +x airootfs/usr/local/bin/custom-init.sh

Building the ISO Image

Build Process

Execute the build with proper parameters:

# Build ISO with verbose output
mkarchiso -v -w ~/custom-arch-iso/work -o ~/custom-arch-iso/output ~/custom-arch-iso/profile/

Build Options

-v: Verbose output for debugging
-w: Work directory (use tmpfs for performance)
-o: Output directory for final ISO
Profile path: Location of customized profile

Performance Optimization

For faster builds, utilize tmpfs for high-performance temporary storage:

# Use tmpfs for work directory
sudo mount -t tmpfs -o size=4G tmpfs ~/custom-arch-iso/work
 
# Parallel compression
export COMPRESSXZ=(xz -T 0)

The tmpfs operations guide explains how to configure memory-based filesystems for optimal build performance.

Testing the Custom ISO

Legacy BIOS Testing

# Test in legacy BIOS mode
run_archiso -i ~/custom-arch-iso/output/archlinux-custom.iso

UEFI Testing

# Test in UEFI mode
run_archiso -u -i ~/custom-arch-iso/output/archlinux-custom.iso

Virtual Machine Testing

# Using QEMU directly
qemu-system-x86_64 -cdrom ~/custom-arch-iso/output/archlinux-custom.iso \
    -boot d -m 2048 -enable-kvm

Verification Steps

Boot the ISO successfully
Verify network connectivity
Test package installation from local repository
Confirm custom configurations are applied
Validate installation tools functionality

Advanced Features

Calamares Installer Integration

To include the Calamares graphical installer:

Add Calamares to packages:

echo "calamares" >> packages.x86_64

Configure Calamares:

# Create Calamares configuration
mkdir -p airootfs/etc/calamares
# Add configuration files for your specific setup

Automated Installation Scripts

Create unattended installation capabilities:

# Create automated installation script
cat > airootfs/usr/local/bin/auto-install.sh << 'EOF'
#!/bin/bash
# Automated installation script
# Include your installation logic here
EOF

Custom Kernel Configuration

For specialized hardware support:

# Include custom kernel packages
echo "linux-custom" >> packages.x86_64
# Ensure custom kernel is available in local repository

CI/CD Pipeline Integration

GitLab CI Configuration

Create .gitlab-ci.yml for automated builds:

stages:
  - build
  - test
  - deploy
 
build_iso:
  stage: build
  script:
    - mkarchiso -v -w /tmp/work -o ./output ./profile/
  artifacts:
    paths:
      - output/*.iso
    expire_in: 1 week

Build Triggers

Set up automated builds for:

Repository changes
Package updates
Scheduled builds for security updates

Testing Pipeline

Include automated testing:

test_iso:
  stage: test
  script:
    - run_archiso -i output/*.iso
    - # Additional testing commands

Troubleshooting Common Issues

Build Failures

Package conflicts: Use pacman troubleshooting techniques:

# Check package dependencies
pacman -Si package-name
# Resolve conflicts in packages.x86_64

Insufficient space:

# Monitor disk usage during build
df -h /tmp/work
# Increase tmpfs size if needed

Boot Issues

Missing firmware:

# Add firmware packages
echo "linux-firmware" >> packages.x86_64

Network problems:

# Verify network service configuration
systemctl status NetworkManager

Repository Problems

GPG key issues: Ensure proper GPG key management and trust configuration:

# Import keys in live environment
pacman-key --init
pacman-key --populate archlinux

Package signing: Follow the GPG signing procedures:

# Sign packages before adding to repository
gpg --detach-sign package.pkg.tar.xz

Best Practices

Security Considerations

Always sign custom packages with GPG
Regularly update base system packages
Minimize attack surface by excluding unnecessary packages
Implement secure boot configuration when possible

Performance Optimization

Use tmpfs for build directories
Enable parallel compression
Optimize package selection for intended use case
Consider using ccache for repeated builds

Maintenance Strategy

Automate security updates
Regular testing of ISO functionality
Version control all configuration files
Document all customizations

Distribution Management

Maintain changelog for ISO versions
Implement proper versioning scheme
Provide clear installation documentation
Consider end-user support requirements

References and Resources

Official Documentation

Calamares: Universal installer framework
Pacman: Package management system
QEMU: Virtualization for testing
GitLab CI: Continuous integration platform

Community Resources

Arch Linux Forums
Reddit /r/archlinux
IRC archlinux on Libera.Chat
GitHub archiso repository

Questions Answered in This Document

Q: How do I create a custom Arch Linux ISO with my own packages? A: Use archiso to build a custom ISO by copying the releng profile, adding your packages to packages.x86_64, including a local repository in the airootfs directory, and building with mkarchiso.

Q: Can I include a local package repository in my custom ISO? A: Yes, create a local repository structure, add it to the airootfs/repo directory, configure pacman.conf to include the repository, and ensure GPG keys are properly managed for package verification.

Q: What’s the difference between legacy and UEFI testing for custom ISOs? A: Legacy testing uses run_archiso -i for BIOS systems, while UEFI testing uses run_archiso -u -i for modern UEFI systems. Both are important for compatibility testing.

Q: How can I automate the ISO build process? A: Implement a CI/CD pipeline using GitLab CI, GitHub Actions, or similar tools. Create build scripts that handle the mkarchiso process and include automated testing steps.

Q: What should I do if my custom ISO fails to boot? A: Check for missing firmware packages, verify boot loader configuration, ensure all required packages are included, and test in both legacy and UEFI modes to isolate the issue.

Q: How do I include the Calamares installer in my custom ISO? A: Add “calamares” to your packages.x86_64 file, create appropriate configuration files in airootfs/etc/calamares, and ensure all installation dependencies are included.

Q: Why should I use tmpfs for the build work directory? A: O operations, reduces wear on SSDs, and automatically cleans up temporary files. Mount with sufficient size (4GB+) using mount -t tmpfs -o size=4G tmpfs /work/dir.

Q: How do I sign custom packages for my repository? A: Generate a GPG key, sign packages with gpg --detach-sign package.pkg.tar.xz, add the repository with appropriate SigLevel configuration, and include the public key in the ISO.

Q: What’s the recommended testing process for custom ISOs? A: Test in both legacy BIOS and UEFI modes, verify all custom features work correctly, test network connectivity, validate package installation from local repository, and perform installation testing.

Q: How can I optimize build performance for large custom ISOs? A: Use tmpfs for work directories, enable parallel compression with COMPRESSXZ=(xz -T 0), use ccache for repeated builds, and minimize package selection to reduce build time.

Flouda Vault

Creating Custom Arch Linux ISO Images with Local Repository Support

What You’ll Learn

Prerequisites

Core Components Overview

Archiso Framework

Essential Elements

Project Structure and Planning

Recommended Directory Layout

Build Environment Setup

Setting Up the Build Environment

Installing Required Packages

Copying Base Profile

Integrating Local Package Repository

Repository Structure

GPG Key Management

Repository Integration

Customizing the Live Environment

Package Selection

System Configuration

Custom Scripts and Hooks

Building the ISO Image

Build Process

Build Options

Performance Optimization

Testing the Custom ISO

Legacy BIOS Testing

UEFI Testing

Virtual Machine Testing

Verification Steps

Advanced Features

Calamares Installer Integration

Automated Installation Scripts

Custom Kernel Configuration

CI/CD Pipeline Integration

GitLab CI Configuration

Build Triggers

Testing Pipeline

Troubleshooting Common Issues

Build Failures

Boot Issues

Repository Problems

Best Practices

Security Considerations

Performance Optimization

Maintenance Strategy

Distribution Management

References and Resources

Official Documentation

Related Tools

Community Resources

Questions Answered in This Document

Graph View

Table of Contents

Backlinks