secubox-deb/docs/wiki/Build-System.md

Build System

SecuBox-DEB provides multiple build scripts for creating bootable images targeting different platforms.

---

Quick Start

# Live USB for x64 (kiosk + autologin enabled by default)
sudo bash image/build-live-usb.sh

# ARM64 board (MOCHAbin)
sudo bash image/build-image.sh --board mochabin

# VirtualBox VM
sudo bash image/build-image.sh --board vm-x64 --vdi

---

Build Scripts

Script	Target	Output
build-live-usb.sh	x64 Live USB	.img / .img.gz
build-image.sh	ARM64 boards / x64 VM	.img / .vdi
build-rpi-usb.sh	Raspberry Pi 400	.img
build-installer-iso.sh	x64 ISO installer	.iso
create-vbox-vm.sh	VirtualBox VM	VM config

---

Live USB (x64)

The primary build target for testing and deployment on x64 hardware.

Command

sudo bash image/build-live-usb.sh [OPTIONS]

Options

Option	Description	Default
--suite SUITE	Debian suite	bookworm
--size SIZE	Image size	8G
--local-cache	Use local APT cache	Off
--no-kiosk	Disable GUI kiosk	Kiosk ON
--no-persistence	No persistent partition	Persistence ON
--no-compress	Skip gzip (faster build)	Compress ON
--preseed FILE	Include preseed config	None
--overlay	Advanced overlay layout	Off

Features

• UEFI + Legacy BIOS hybrid boot
• Root autologin on console (TTY1-6)
• GUI kiosk mode on TTY7 (Chromium fullscreen)
• Network auto-detection at first boot
• Persistence partition for config/data survival
• All SecuBox packages pre-installed (~125 modules)

Output

output/secubox-live-amd64-bookworm.img      # Raw image
output/secubox-live-amd64-bookworm.img.gz   # Compressed

Flash to USB

# Compressed image
zcat output/secubox-live-amd64-bookworm.img.gz | sudo dd of=/dev/sdX bs=4M status=progress

# Raw image
sudo dd if=output/secubox-live-amd64-bookworm.img of=/dev/sdX bs=4M status=progress

---

ARM64 Boards

Build images for Marvell Armada-based hardware.

Command

sudo bash image/build-image.sh --board <BOARD> [OPTIONS]

Supported Boards

Board	SoC	Profile	Use Case
mochabin	Armada 7040	SecuBox Pro	Production gateway
espressobin-v7	Armada 3720	SecuBox Lite	Small office
espressobin-ultra	Armada 3720	SecuBox Lite+	Extended storage

Options

Option	Description	Default
--board BOARD	Target board	mochabin
--suite SUITE	Debian suite	bookworm
--size SIZE	Image size	8G
--vdi	Also create VDI	Off
--local-cache	Use local APT cache	Off
--slipstream	Include local .deb packages	ON

Examples

# MOCHAbin (default)
sudo bash image/build-image.sh --board mochabin

# ESPRESSObin v7
sudo bash image/build-image.sh --board espressobin-v7

# With local package cache
sudo bash image/build-image.sh --board mochabin --local-cache --slipstream

---

VirtualBox VM

Build and run SecuBox in VirtualBox for development/testing.

Build Image

sudo bash image/build-image.sh --board vm-x64 --vdi

Create VM

bash image/create-vbox-vm.sh output/secubox-vm-x64-bookworm.vdi

Run VM

bash scripts/run-vbox.sh

Port Forwarding (NAT)

Service	Host Port	Guest Port
SSH	2222	22
HTTPS	9443	443
HTTP	8080	80

Connect

ssh -p 2222 root@localhost
# Password: secubox

---

Local Build Cache

Speed up builds using local APT cache.

Setup (once)

sudo bash scripts/setup-local-cache.sh

Build with Cache

sudo bash image/build-live-usb.sh --local-cache
sudo bash image/build-image.sh --board mochabin --local-cache

---

Slipstream Local Packages

Include locally-built .deb packages in the image.

Build Packages

bash scripts/build-all-local.sh bookworm amd64
# Output: output/debs/*.deb

Include in Image

sudo bash image/build-live-usb.sh --slipstream

The build script automatically includes all .deb files from output/debs/.

---

First Boot

The firstboot.sh script runs automatically on first boot:

1. Board detection - Identifies hardware platform
2. SSH keys - Generates unique host keys
3. JWT secrets - Creates API authentication tokens
4. Hostname - Sets secubox-<board> hostname
5. Network - Applies netplan configuration
6. nftables - Loads firewall rules
7. Services - Enables SecuBox services

Manual Trigger

sudo /usr/lib/secubox/firstboot.sh

---

Kiosk Mode

GUI kiosk mode provides a fullscreen Chromium browser on TTY7.

Enable/Disable

# Status
secubox-kiosk-setup status

# Enable
secubox-kiosk-setup enable

# Disable (console only)
secubox-kiosk-setup disable

Services

Service	Description
secubox-kiosk.service	X11 kiosk (TTY7)
secubox-console.service	TUI dashboard

Boot Parameters

# In GRUB/kernel cmdline
secubox.kiosk=1    # Enable kiosk
secubox.kiosk=0    # Disable kiosk

---

Preseed Configuration

Pre-configure a SecuBox installation with custom settings.

Create Preseed Archive

tar -czvf preseed.tar.gz \
  etc/secubox/*.toml \
  etc/netplan/*.yaml \
  etc/wireguard/*.conf

Build with Preseed

sudo bash image/build-live-usb.sh --preseed preseed.tar.gz

Apply Manually

sudo /usr/lib/secubox/preseed-apply.sh /path/to/preseed.tar.gz

---

Troubleshooting

Build Fails at Debootstrap

# Clear cache and retry
sudo rm -rf /tmp/secubox-rootfs
sudo bash image/build-live-usb.sh

VirtualBox NVRAM Error

# Remove corrupted NVRAM file
rm "/home/$USER/VirtualBox VMs/SecuBox-*/SecuBox-*.nvram"
VBoxManage startvm "SecuBox-VM-x64" --type gui

SSH Connection Refused

1. Check VM is fully booted (login prompt visible)
2. Verify port forwarding: VBoxManage showvminfo "SecuBox-VM-x64" | grep NAT
3. Check SSH service: systemctl status ssh (inside VM)

Kiosk Not Starting

# Check logs
journalctl -u secubox-kiosk -f

# Verify X11
ls /tmp/.X11-unix/

# Manual start
startx /usr/bin/chromium --kiosk http://localhost

---

Version History

Version	Date	Changes
1.9.0	2026-05	Health banner, CDN injection
1.8.0	2026-04	125 modules, SOC dashboard
1.7.0	2026-03	Kiosk mode, TUI console
1.6.0	2026-02	Live USB, persistence

---

See Also

• Home - Wiki home
• Architecture-Boot - Boot process details
• Developer-Guide - Development setup
• QEMU-ARM64 - ARM64 emulation