Quick Start Guide - Terminal Installer

Overview

The terminal installer provides a simple, reliable alternative to Calamares GUI installer. It boots from a minimal ISO, stays in terminal mode, and uses automated scripts to install Debian Atomic.

Quick Commands

# Build the installer
just build

# Create bootable ISO
just create-iso

# Test in QEMU
just test-iso

# Create test VM with disk
just create-test-vm

# Run installation tests
sudo scripts/test-install.sh

Installation Process

Boot from ISO - Boot the minimal installer ISO
Run installer - Execute sudo install-debian-atomic
Follow prompts - Confirm partitioning and installation
Reboot - Boot into the new Debian Atomic system

Features

✅ Automated partitioning - GPT with boot, root, and swap partitions
✅ User creation - Creates default user with sudo access
✅ Network configuration - DHCP with systemd-networkd
✅ Bootc integration - Installs and configures bootc
✅ Minimal dependencies - No GUI requirements
✅ Reliable - Fewer moving parts than Calamares

Advantages over Calamares

Simpler - No GUI dependencies or complex configuration
More reliable - Fewer components that can fail
Easier to debug - Clear terminal output and logging
Consistent - Uses same atomic principles as the rest of the system
Automated - Can be fully automated for testing

Configuration

Edit config/installer.conf to customize:

Target device detection
User account settings
Partition sizes
Network configuration
Package selection

Testing

The scripts/test-install.sh script verifies the installation process works correctly by:

Creating test disk image
Testing partitioning
Testing filesystem creation
Testing base system installation
Testing user creation
Testing network configuration
Testing boot configuration

Troubleshooting

ISO won't boot - Check that kernel and initrd are properly extracted
Installation fails - Check logs in /tmp/install.log
Network issues - Verify DHCP is working or configure static IP
Boot issues - Check that bootc is properly installed

Next Steps

Build and test the terminal installer
Compare performance with Calamares approach
Document any issues or improvements needed
Consider making this the default installer approach

2.4 KiB Raw Blame History