Notes

build_and_test_guide

6 min read

Building and Testing Nanite ISO

This document provides a comprehensive guide for building and testing the Nanite ISO image. It covers the entire process from initial build setup to testing and validation, ensuring a functional AI-powered Linux distribution.

Build Environment Preparation

Before building the Nanite ISO, ensure your build environment is properly configured:

# Create a dedicated build directory
mkdir -p nanite-build
cd nanite-build
 
# Install required packages for building
sudo apt update
sudo apt install -y live-build debootstrap squashfs-tools xorriso isolinux syslinux-common
 
# Ensure sufficient disk space (at least 20GB free)
df -h .
 
# Ensure sufficient memory (at least 4GB recommended)
free -h

Building the Initial ISO

The build process involves several stages and may take significant time depending on your system’s performance and internet connection:

# Initialize the live-build configuration
lb config
 
# Apply all the configuration settings from the configuration guide
# (This includes setting up package lists, hooks, and custom files)
 
# Clean any previous build artifacts
sudo lb clean
 
# Start the build process
sudo lb build 2>&1 | tee build.log

The build process typically follows these stages:

  1. Bootstrap: Creating the base Debian system
  2. Chroot: Installing packages and applying customizations
  3. Binary: Creating the bootable ISO image
  4. Cleanup: Finalizing the build

During the build, you can monitor progress through the terminal output or by checking the build.log file. The entire process may take 30 minutes to several hours depending on your system’s performance and internet connection speed.

Common Build Issues and Solutions

Package Installation Failures

If package installation fails during the build:

# Check the apt logs in the chroot environment
cat chroot/var/log/apt/term.log
 
# Fix package conflicts or missing dependencies
# Edit the package lists in config/package-lists/
# Then clean and rebuild
sudo lb clean
sudo lb build

Hook Script Failures

If hook scripts fail during execution:

# Check the hook execution logs
cat chroot/debootstrap/debootstrap.log
 
# Debug and fix the failing hook script
# Edit the script in config/hooks/live/
# Then clean and rebuild
sudo lb clean
sudo lb build

Space Issues

If the build fails due to insufficient disk space:

# Clean up unnecessary files
sudo apt clean
sudo apt autoremove
 
# Remove previous build artifacts
sudo lb clean --purge
 
# Check available space again
df -h .
 
# Restart the build
sudo lb build

Testing the ISO Image

After successfully building the ISO, it’s crucial to thoroughly test it:

Basic ISO Validation

# Verify the ISO was created
ls -lh *.iso
 
# Check the ISO integrity
md5sum *.iso > nanite.md5

Testing in QEMU

QEMU provides a quick way to test the ISO without creating a full virtual machine:

# Install QEMU if not already installed
sudo apt install -y qemu-system-x86
 
# Test boot with QEMU (allocate at least 4GB RAM and 2 CPU cores)
qemu-system-x86_64 -m 4096 -smp 2 -cdrom nanite-*.iso -boot d

Testing in VirtualBox

For more thorough testing, use VirtualBox:

# Create a new virtual machine
VBoxManage createvm --name "Nanite Test" --ostype Debian_64 --register
 
# Configure the VM with sufficient resources
VBoxManage modifyvm "Nanite Test" --memory 4096 --cpus 2 --vram 128 --graphicscontroller vmsvga
 
# Create a virtual hard disk
VBoxManage createhd --filename "NaniteTest.vdi" --size 20480
 
# Attach the hard disk and the ISO
VBoxManage storagectl "Nanite Test" --name "SATA Controller" --add sata --controller IntelAHCI
VBoxManage storageattach "Nanite Test" --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium "NaniteTest.vdi"
VBoxManage storagectl "Nanite Test" --name "IDE Controller" --add ide
VBoxManage storageattach "Nanite Test" --storagectl "IDE Controller" --port 0 --device 0 --type dvddrive --medium nanite-*.iso
 
# Start the VM
VBoxManage startvm "Nanite Test"

Testing Checklist

During testing, verify the following aspects of the Nanite distribution:

System Boot and Installation

  • ISO boots properly in live mode
  • All hardware is properly detected
  • Installation process works correctly
  • System boots properly after installation

Desktop Environment

  • XFCE desktop loads correctly
  • Panel and desktop icons are visible
  • Theme and appearance match design specifications
  • System menus contain all expected applications

AI Components

  • Ollama service starts automatically
  • Pre-loaded models are available
  • AI Assistant is accessible from panel
  • Command-line AI tools function correctly
  • Speech recognition and synthesis work
  • Image generation capabilities function
  • Code assistance tools are operational

Performance Testing

  • System responsiveness is acceptable
  • Memory usage is within expected range
  • CPU usage during idle is reasonable
  • AI model loading time is acceptable
  • AI response time is reasonable

Debugging and Issue Resolution

If issues are encountered during testing:

System Boot Issues

# Check boot logs
dmesg | less
 
# Check system logs
journalctl -b

AI Component Issues

# Check Ollama service status
systemctl status ollama
 
# Check AI Assistant service status
systemctl status nanite-assistant
 
# Check service logs
journalctl -u ollama
journalctl -u nanite-assistant
 
# Test Ollama directly
ollama run mistral -c "Hello"

Desktop Environment Issues

# Check X server logs
cat /var/log/Xorg.0.log
 
# Check XFCE session logs
cat ~/.xsession-errors

Creating the Final Optimized ISO

After testing and resolving any issues, create an optimized final ISO:

# Clean the build environment
sudo lb clean
 
# Apply optimizations to configuration
# - Reduce included packages if needed
# - Optimize compression settings
lb config --binary-images iso-hybrid --binary-compression xz
 
# Rebuild with optimizations
sudo lb build 2>&1 | tee build_final.log
 
# Verify the final ISO
ls -lh *.iso
md5sum *.iso > nanite_final.md5

Final Validation

Perform a final validation of the optimized ISO:

# Test boot with QEMU
qemu-system-x86_64 -m 4096 -smp 2 -cdrom nanite-*.iso -boot d
 
# Verify all critical functionality
# - System boot
# - Desktop environment
# - AI components
# - Performance

Preparing for Distribution

Once the ISO is fully tested and validated:

# Rename the ISO with version information
mv live-image-amd64.hybrid.iso nanite-ai-linux-$(date +%Y%m%d).iso
 
# Generate checksums
md5sum nanite-ai-linux-*.iso > nanite-ai-linux-$(date +%Y%m%d).md5
sha256sum nanite-ai-linux-*.iso > nanite-ai-linux-$(date +%Y%m%d).sha256
 
# Create a release notes file
cat > release-notes.txt << EOF
Nanite AI Linux $(date +%Y%m%d)
==============================
 
This release includes:
- Debian-based Linux distribution
- XFCE desktop environment
- Integrated AI models via Ollama
- System-wide AI assistant
- Speech recognition and synthesis
- Image generation capabilities
- Code assistance tools
 
System Requirements:
- 4GB RAM minimum (8GB+ recommended)
- 20GB disk space
- x86_64 processor
- GPU recommended for AI acceleration
EOF

Conclusion

Building and testing the Nanite ISO is a multi-stage process that requires careful attention to detail. By following this guide, you can create a functional AI-powered Linux distribution that integrates various AI models and applications into a cohesive system. The resulting ISO can be used for direct installation or as a base for creating virtual machine images.

Remember that building a custom Linux distribution is an iterative process. You may need to go through several build-test-debug cycles before achieving the desired result. Each iteration provides valuable insights and improvements that contribute to the final quality of the distribution.

Graph View

Backlinks