Services.

github-actions[bot] edited this page 2025-12-09 00:01:08 +00:00

Historique 1

Services

Complete guide to available services and creating custom ones.

Available Services

base (Always Included)

Purpose: Essential system configuration for all images

Packages:

raspberrypi-kernel - RaspiOS kernel with RP1 drivers
raspberrypi-bootloader - Boot firmware
firmware-brcm80211 - WiFi/Bluetooth firmware
NetworkManager - Network management
openssh-server - SSH access
Essential utilities

Configuration:

RaspiOS APT repository + pinning
Network bridges (br-wan, br-lan if dual NIC)
SSH enabled
MOTD with IP addresses

First-boot actions:

Partition resize to fill SD card
Network interface name persistence
Bridge configuration based on detected NICs

qemu

Purpose: Incus container/VM platform with KVM acceleration

Dependencies: None

Packages:

qemu-kvm - KVM virtualization
incus - Container/VM manager
incus-tools - Management utilities

Configuration:

Incus initialization with default profile
Network bridges: br-wan (WAN), br-lan (LAN if dual NIC)
Storage pool: default (dir backend)

First-boot actions:

Create br-lan and br-wan bridges (if not exist)
Configure Incus network integration
Enable IP forwarding and NAT

Use cases:

Run VMs (Home Assistant, OpenWrt)
Create containers for isolated services
Development environments

docker

Purpose: Docker Engine with Portainer and Watchtower

Dependencies: None

Packages:

docker-ce - Docker Engine
docker-ce-cli - Docker CLI
containerd.io - Container runtime

Configuration:

Docker installed from official repository
User pi added to docker group

First-boot actions:

Deploy Portainer (web UI for Docker)
Deploy Watchtower (automatic container updates)
Configure bridge networking

Services deployed:

Portainer: https://raspberry-ip:9443
Watchtower: Automatic updates for containers

Use cases:

Run containerized applications
Manage containers via web UI
Auto-update containers

haos

Purpose: Home Assistant OS in an Incus VM

Dependencies: qemu (Incus required)

Packages: None (VM image downloaded at first boot)

First-boot actions:

Download Home Assistant OS image (latest stable)
Create Incus VM named haos
Allocate resources (2 vCPUs, 4GB RAM, 24GB disk)
Configure network bridge (br-lan or br-wan)
Detect and pass through USB Zigbee coordinators
Start VM

Zigbee auto-detection:

Scans /dev/ttyUSB* and /dev/ttyACM*
Detects ConBee, CC2652, Sonoff, Silicon Labs dongles
Passes through via USB vendor/product ID

Access:

Home Assistant: http://raspberry-ip:8123
First boot setup takes 5-10 minutes

Use cases:

Home automation platform
Zigbee/Z-Wave integration
IoT device management

openwrt

Purpose: OpenWrt router in an Incus container

Dependencies: qemu (Incus required)

Packages: None (container image downloaded at first boot)

First-boot actions:

Download OpenWrt rootfs image
Create Incus container named openwrt
Allocate resources (1 vCPUs, 1GB RAM, 24GB disk)
Configure network: eth0 → br-wan, eth1 → br-lan
Set static IP: 192.168.10.1/24
Start container

Network configuration:

WAN: br-wan (DHCP client)
LAN: br-lan (192.168.10.1, DHCP server)

Access:

LuCI web UI: http://192.168.10.1
SSH: ssh root@192.168.10.1

Use cases:

Advanced routing and firewall
VPN server/client
QoS and traffic shaping
Network monitoring

hotspot

Purpose: WiFi access point (2.4GHz/5GHz)

Dependencies: None

Packages:

hostapd - WiFi access point daemon

Configuration files:

hostapd-5ghz.conf - 5GHz AP config
hostapd-2.4ghz.conf - 2.4GHz AP config

First-boot actions:

Detect WiFi interfaces (wlan0, wlan1)
Configure hostapd based on detected adapters:
- Dual WiFi: 2.4GHz (wlan0) + 5GHz (wlan1)
- Single WiFi: 5GHz (wlan0)
Attach to br-lan (if exists) or br-wan
Disable NetworkManager management of WiFi
Start hostapd services

Default credentials:

SSID: RaspberryPi-WIFI
Password: raspberry

Use cases:

WiFi access for IoT devices
Guest network
Extend network coverage

Service Combination Examples

Minimal Development Platform

./bin/autobuild --image debian

Base Debian with RaspiOS kernel
SSH access
Network bridges

Docker Host

./bin/autobuild --image debian/docker

Docker Engine
Portainer web UI
Watchtower auto-updates

Virtualization Platform

./bin/autobuild --image debian/qemu

Incus containers/VMs
KVM acceleration

Home Automation Gateway

./bin/autobuild --image debian/qemu+haos

Home Assistant OS VM
Zigbee dongle auto-detection
Web UI on port 8123

Network Router + WiFi AP

./bin/autobuild --image debian/qemu+openwrt+hotspot

OpenWrt routing
Dual-band WiFi hotspot
Advanced firewall/QoS

Full Stack

./bin/autobuild --image debian/qemu+docker+openwrt+hotspot+haos

All services combined
Ideal for Raspberry Pi 5 with 8GB RAM

Creating Custom Services

Service Directory Structure

images/debian/services/myservice/
├── setup.sh              # Required: package installation (runs in QEMU)
├── first-boot/
│   └── init.sh           # Optional: runtime config (runs on first boot)
├── setupfiles/           # Optional: static files → /etc/setupfiles/
│   ├── config.conf
│   └── script.sh
├── depends.sh            # Optional: dependencies
└── motd.sh               # Optional: MOTD content

setup.sh (Package Installation)

Executed in QEMU ARM64 during build.

Template:

#!/bin/bash
set -e

# Install packages
apt update
apt install -y package1 package2

# Configure system
systemctl enable my-service

# Copy files
cp /etc/setupfiles/config.conf /etc/my-service/

Best practices:

Use set -e to exit on errors
Install packages from Debian repositories when possible
Add custom repositories if needed
Enable systemd services that should start at boot
Don't start services (no network in QEMU)

first-boot/init.sh (Runtime Configuration)

Executed on first boot on Raspberry Pi.

Template:

#!/bin/bash
set -e

# Detect hardware
if ip link show eth1 >/dev/null 2>&1; then
    BRIDGE="br-lan"
else
    BRIDGE="br-wan"
fi

# Download resources
wget https://example.com/resource.tar.gz -O /tmp/resource.tar.gz

# Create containers/VMs
incus launch images:alpine mycontainer

# Configure services
systemctl start my-service

Best practices:

Detect hardware and adapt configuration
Download large files here (not in setup.sh)
Create containers/VMs
Start services
Use /etc/setupfiles/ for configuration files

depends.sh (Dependencies)

Declare dependencies on other services.

Example:

# myservice depends on qemu
DEPENDS_ON="qemu"

Dependency resolution:

Dependencies are automatically included
Build order is adjusted to satisfy dependencies

motd.sh (Message of the Day)

Display service information on login.

Example:

cat <<'EOF'
My Service UI: https://raspberry-ip:8080
Username: admin
Password: (set on first access)
EOF

setupfiles/ (Static Files)

Static configuration files copied to /etc/setupfiles/.

Access in scripts:

# In setup.sh or first-boot/init.sh
cp /etc/setupfiles/myconfig.conf /etc/my-service/

Service Development Workflow

1. Create Service Directory

mkdir -p images/debian/services/myservice/first-boot
mkdir -p images/debian/services/myservice/setupfiles

2. Write setup.sh

cat > images/debian/services/myservice/setup.sh <<'EOF'
#!/bin/bash
set -e

apt update
apt install -y nginx

systemctl enable nginx
EOF

chmod +x images/debian/services/myservice/setup.sh

3. Write first-boot/init.sh (Optional)

cat > images/debian/services/myservice/first-boot/init.sh <<'EOF'
#!/bin/bash
set -e

# Configure nginx with custom config
cp /etc/setupfiles/nginx.conf /etc/nginx/sites-available/default
systemctl restart nginx
EOF

chmod +x images/debian/services/myservice/first-boot/init.sh

4. Add Configuration Files (Optional)

cat > images/debian/services/myservice/setupfiles/nginx.conf <<'EOF'
server {
    listen 80;
    root /var/www/html;
    index index.html;
}
EOF

5. Add MOTD (Optional)

cat > images/debian/services/myservice/motd.sh <<'EOF'
cat <<'MOTD'
Nginx: http://raspberry-ip/
MOTD
EOF

chmod +x images/debian/services/myservice/motd.sh

6. Test Service

# Build image with your service
./bin/autobuild --image debian/myservice

# Flash and boot
sudo dd if=debian-myservice.img of=/dev/sdX bs=4M status=progress

# Check logs on first boot
sudo journalctl -u services-first-boot

7. Debug Issues

QEMU stage issues:

# Check QEMU logs
cat images/debian-myservice/qemu-*.log

# Manually test in QEMU
./bin/autobuild --image debian/myservice --skip-compress

First-boot stage issues:

# On Raspberry Pi, check logs
sudo journalctl -u services-first-boot -f

# Check service status
sudo systemctl status myservice

Service Best Practices

Package Installation

Install in setup.sh, not first-boot/init.sh
Use official Debian repositories when possible
Pin package versions if stability critical

Resource Downloads

Download large files in first-boot/init.sh
Don't download in setup.sh (slows QEMU)
Cache downloads in /var/cache/ if appropriate

Hardware Detection

Always detect hardware in first-boot/init.sh
Adapt configuration based on detection
Fail gracefully if hardware missing

Error Handling

Use set -e to exit on errors
Log errors to journald
Provide helpful error messages

Network Configuration

Use existing bridges (br-wan, br-lan)
Don't create new bridges unless necessary
Check bridge existence before use

Security

Don't hardcode passwords in scripts
Use strong default passwords (prompt user to change)
Enable firewall if service exposed

Next Steps

Cloner la documentation