Test-Workflows

Diese Anleitung bündelt die plattformspezifischen Test-Workflows, die früher in der Haupt-README.md standen. Einen schnellen Überblick über die unterstützten Plattformen gibt die plattformübergreifende Matrix in der README im Stammverzeichnis. Konkrete Befehle finden Sie in den folgenden Abschnitten.

Einheitlicher VM-Workflow

Die meisten VM-basierten Test-Workflows durchlaufen vom Repository-Stammverzeichnis aus denselben Lebenszyklus:

sailwright build <osname> [--type <type>] [--arch <arch>]
sailwright create <osname> [--type <type>] [--arch <arch>]
sailwright start <osname> [--type <type>] [--arch <arch>]
sailwright provision <osname> [--type <type>] [--arch <arch>] --check
sailwright provision <osname> [--type <type>] [--arch <arch>]
sailwright stop <osname> [--type <type>] [--arch <arch>]
sailwright destroy <osname> [--type <type>] [--arch <arch>]

build erstellt oder aktualisiert das wiederverwendbare VM-Artefakt.
create legt aus diesem Artefakt die verwaltete Ziel-VM an.
start startet eine bereits angelegte VM, die gestoppt ist.
provision führt den Ansible-Workflow auf der laufenden Zielumgebung aus.
stop fährt die VM herunter, ohne sie zu löschen.
destroy entfernt die verwaltete Ziel-VM.

Je nach Backend erfolgt der erste Start bereits bei create, oder er erfordert einen kleinen hostspezifischen Schritt. Nachdem eine VM angelegt wurde, starten Sie sie mit start jederzeit erneut.

Mit den list-Unterbefehlen sehen Sie, was Ihr aktueller Host unterstützt:

sailwright build list
sailwright create list
sailwright start list
sailwright provision list
sailwright stop list
sailwright destroy list

Mit --help am Hauptbefehl oder an jedem Unterbefehl rufen Sie die unterstützten Optionen und Details zur Verwendung auf:

sailwright --help
sailwright create --help
sailwright start --help
sailwright provision --help

Den vollautomatischen, aufgezeichneten End-to-End-Lauf des gesamten Lebenszyklus mit einem einzigen Befehl (install -> build -> create -> start -> provision --check -> provision -> (stop -> destroy)) beschreibt der Automatisierte Schnellstart.

Workflow für das OCI-Build-Artefakt-Registry

Fertige Build-Artefakte lassen sich in ein OCI-Registry hochladen und daraus herunterladen. Die Befehle verwenden dasselbe Vokabular für Zielumgebungen wie der VM-Workflow und ein Docker-ähnliches Referenzargument:

sailwright push list
sailwright pull list

sailwright push localhost:5000/sailwright/ubuntu-server-amd64:qemu \
  --plain-http \
  --os ubuntu \
  --type server \
  --arch amd64 \
  --host-os linux

sailwright pull localhost:5000/sailwright/ubuntu-server-amd64:qemu \
  --plain-http \
  --os ubuntu \
  --type server \
  --arch amd64 \
  --host-os linux

Der OCI-Client liest standardmäßig die Docker-Zugangsdaten, sodass docker login für Registries mit Authentifizierung funktioniert. Verwenden Sie --username, --password-stdin oder --access-token, wenn Sie befehlsspezifische Zugangsdaten angeben möchten.

Der Linux-Build-Workflow in GitHub Actions veröffentlicht fertige Ubuntu-Artefakte bei Pushes auf main und bei manuellen workflow_dispatch-Läufen, die von main aus gestartet werden, in der GitHub Container Registry. Die Artefakte liegen unter ghcr.io/<owner>/ubuntu-24; die Tags folgen dem Schema <type>-<arch>-<hostos>-build, zum Beispiel:

ghcr.io/csautter/ubuntu-24:server-amd64-linux-build
ghcr.io/csautter/ubuntu-24:desktop-arm64-linux-build

Build-Artefakte für Windows-VMs werden absichtlich nicht veröffentlicht.

Für HTTPS-Registries mit internem oder selbstsigniertem Zertifikat fügen Sie am besten die CA des Registrys mit --ca-file /path/to/ca.pem hinzu. Für kurzzeitige Tests gegen ein Registry, dem Sie bereits vertrauen, deaktiviert --insecure-skip-tls-verify die Prüfung des TLS-Zertifikats.

Für ein lokales zot-Registry verwenden Sie --plain-http. So führen Sie den optionalen Integrationstest gegen dieses Registry aus:

DEV_ALCHEMY_OCI_INTEGRATION_REF=localhost:5000/sailwright/integration:oci \
DEV_ALCHEMY_OCI_INTEGRATION_PLAIN_HTTP=true \
go test ./pkg/oci -run TestOCIRegistryPushPullIntegration -count=1

Das hochgeladene Artefakt ist ein gewöhnliches OCI-Artefakt, sodass Sie es auch mit ORAS untersuchen können:

oras manifest fetch --plain-http localhost:5000/sailwright/ubuntu-server-amd64:qemu

Lokales Host-Provisioning

Verwenden Sie den gemeinsamen lokalen Wrapper, wenn Sie das Playbook auf den aktuellen Rechner anwenden möchten statt auf eine verwaltete VM:

sailwright provision local --check
sailwright provision local --proto ssh --check
sailwright provision local --playbook ./playbooks/setup.yml --check
sailwright provision local

Plattform-Standardwerte, die Auflösung des konfigurierten Playbooks, erweiterte Optionen und das Aufräumverhalten unter Windows beschreibt Lokales Provisioning.

Systemunabhängiger Docker-Workflow

Ubuntu-Rollentests unter Linux, WSL, Windows oder macOS

Mit dem mitgelieferten Docker-Compose-Setup führen Sie das auf Ubuntu ausgerichtete Ansible-Playbook in einem Container aus:

docker compose -f deployments/docker-compose/ansible/docker-compose.yml up

Räumen Sie anschließend auf mit:

docker compose -f deployments/docker-compose/ansible/docker-compose.yml down

Workflows für Linux-Hosts

Ubuntu unter Linux mit QEMU/KVM und virt-manager

Installieren Sie zuerst die Host-Abhängigkeiten:

sailwright install

sailwright install installiert die libvirt- und QEMU-Pakete für den Host. Bei manchen Distributionen ist vor dem Start der verwalteten VM dennoch ein manueller Schritt auf dem Host nötig: Aktivieren Sie das default-Netzwerk von libvirt, oder gewähren Sie ACL-/Gruppenzugriff auf das System-Image-Verzeichnis von libvirt, falls der Daemon Gäste unter einem anderen Benutzer ausführt.

Erstellen und legen Sie die Ubuntu-VM an:

arch=amd64 # or arm64
type=desktop # or server
sailwright build ubuntu --arch "$arch" --type "$type"
sailwright create ubuntu --arch "$arch" --type "$type"

Standardmäßig verwendet der Linux-Workflow für create/start/stop/destroy die libvirt-Systemverbindung (qemu:///system). Die VM hängt dadurch am Standard-NAT-Netzwerk von libvirt und hat im Normalfall ausgehenden Internetzugang. Verwaltete QCOW2-Datenträger liegen standardmäßig unter /var/tmp/dev-alchemy/libvirt/images; dafür müssen Sie vorab kein Image-Verzeichnis anlegen, das root gehört. Sailwright legt verwaltete Image-Verzeichnisse mit dem Modus 0750 an. Falls Ihr System-libvirt-Daemon Gäste unter einem anderen Benutzer ausführt, gewähren Sie den Zugriff explizit über einen libvirt-Storage-Pool, über Gruppenbesitz bzw. ACLs auf DEV_ALCHEMY_LIBVIRT_IMAGE_DIR oder nutzen Sie die unten beschriebene Session-Verbindung.

Wenn eine VM ein benanntes libvirt-Netzwerk verwendet, prüft Sailwright es vorab, bevor es die Domain definiert oder startet. Mit dem Standard-System-URI läuft dabei diese Prüfung:

virsh --connect qemu:///system net-info default

Existiert das default-Netzwerk, ist aber inaktiv, aktivieren Sie es mit:

sudo virsh --connect qemu:///system net-start default
sudo virsh --connect qemu:///system net-autostart default

Wenn Sie stattdessen die rootlose libvirt-Benutzersitzung bevorzugen, setzen Sie:

export DEV_ALCHEMY_LIBVIRT_URI=qemu:///session
# Optional when you want a custom storage location for the session connection:
export DEV_ALCHEMY_LIBVIRT_IMAGE_DIR="$HOME/.local/share/dev-alchemy/libvirt/images"

Der integrierte Session-Pfad nutzt das User-Mode-Networking von libvirt und benötigt daher das NAT-Netzwerk default nicht. Wird später für einen Session-URI ein benanntes Netzwerk konfiguriert, läuft dieselbe Vorabprüfung gegen qemu:///session.

Wenn Sie stattdessen den herkömmlichen System-Speicherort von libvirt für Images bevorzugen, setzen Sie:

export DEV_ALCHEMY_LIBVIRT_URI=qemu:///system
export DEV_ALCHEMY_LIBVIRT_IMAGE_DIR=/var/lib/libvirt/images/dev-alchemy

Anschließend starten Sie die angelegte VM entweder über virt-manager oder über die CLI:

sailwright start ubuntu --arch "$arch" --type "$type"
sailwright provision ubuntu --arch "$arch" --type "$type" --check
sailwright provision ubuntu --arch "$arch" --type "$type"
sailwright stop ubuntu --arch "$arch" --type "$type"
sailwright destroy ubuntu --arch "$arch" --type "$type"

Der Provisioning-Wrapper ermittelt die IP-Adresse des libvirt-Gasts mit virsh domifaddr und führt ansible-playbook mit einem Inline-SSH-Inventory-Ziel aus. Optionale Überschreibungen für das Ubuntu-Provisioning legen Sie in .env oder in der Prozessumgebung mit LIBVIRT_UBUNTU_ANSIBLE_* fest:

LIBVIRT_UBUNTU_ANSIBLE_USER=packer
LIBVIRT_UBUNTU_ANSIBLE_PASSWORD=P@ssw0rd!
LIBVIRT_UBUNTU_ANSIBLE_BECOME_PASSWORD=P@ssw0rd!
# Optional (defaults shown):
LIBVIRT_UBUNTU_ANSIBLE_CONNECTION=ssh
LIBVIRT_UBUNTU_ANSIBLE_SSH_COMMON_ARGS=-o StrictHostKeyChecking=no -o ServerAliveInterval=10 -o ServerAliveCountMax=3 -o ControlMaster=no -o ControlPersist=no
LIBVIRT_UBUNTU_ANSIBLE_SSH_TIMEOUT=120
LIBVIRT_UBUNTU_ANSIBLE_SSH_RETRIES=3

Weiterführende Anleitung:

Ubuntu Packer README

Windows unter Linux mit QEMU/KVM und virt-manager

Installieren Sie zuerst die Host-Abhängigkeiten:

sailwright install

Erstellen und legen Sie die Windows-11-VM an:

arch=amd64 # or arm64
sailwright build windows11 --arch "$arch" --headless
sailwright create windows11 --arch "$arch"

Anschließend starten Sie die angelegte VM entweder über virt-manager oder über die CLI:

sailwright start windows11 --arch "$arch"

Der Lebenszyklus verwendet dieselben libvirt-Standardwerte wie Ubuntu unter Linux: qemu:///system und verwaltete Datenträger unter /var/tmp/dev-alchemy/libvirt/images, sofern DEV_ALCHEMY_LIBVIRT_URI oder DEV_ALCHEMY_LIBVIRT_IMAGE_DIR nicht gesetzt ist.

Ist /dev/kvm nicht verfügbar oder unzuverlässig, setzen Sie DEV_ALCHEMY_QEMU_FORCE_SOFTWARE_EMULATION=1. Damit überspringen Sie die KVM-Prüfung und erzwingen die Software-Emulation QEMU TCG.

Legen Sie die WinRM-Zugangsdaten in der .env im Projektstamm oder in der Prozessumgebung fest:

LIBVIRT_WINDOWS_ANSIBLE_USER=Administrator
LIBVIRT_WINDOWS_ANSIBLE_PASSWORD=your-secure-password
# Optional (defaults shown):
LIBVIRT_WINDOWS_ANSIBLE_CONNECTION=winrm
LIBVIRT_WINDOWS_ANSIBLE_WINRM_TRANSPORT=basic
LIBVIRT_WINDOWS_ANSIBLE_PORT=5985

Provisionieren Sie die VM vom Repository-Stammverzeichnis aus:

sailwright provision windows11 --arch "$arch" --check
sailwright provision windows11 --arch "$arch"
sailwright stop windows11 --arch "$arch"
sailwright destroy windows11 --arch "$arch"

Der Provisioning-Wrapper ermittelt die IP-Adresse des libvirt-Gasts mit virsh domifaddr und führt ansible-playbook mit einem Inline-WinRM-Inventory-Ziel aus.

Weiterführende Anleitung:

Windows Packer README

Workflows für Windows-Hosts

Ubuntu unter Windows mit Hyper-V

Installieren Sie zuerst die Host-Abhängigkeiten:

sailwright.exe install

Erstellen Sie das Ubuntu-Artefakt:

# server
sailwright.exe build ubuntu --type server --arch amd64
# desktop
sailwright.exe build ubuntu --type desktop --arch amd64

Legen Sie die VM an:

$env:VAGRANT_HYPERV_SWITCH = "Default Switch"
sailwright.exe create ubuntu --type server --arch amd64
# or desktop
sailwright.exe create ubuntu --type desktop --arch amd64

Provisionieren Sie sie:

sailwright.exe provision ubuntu --type server --arch amd64 --check
sailwright.exe provision ubuntu --type server --arch amd64

Der Befehl ermittelt die IP-Adresse der VM automatisch und führt Ansible über den Windows/Cygwin-Wrapper aus. Optionale Überschreibungen für das Ubuntu-Provisioning legen Sie in .env mit HYPERV_UBUNTU_ANSIBLE_* fest.

Weiterführende Anleitungen:

Windows unter Windows mit Docker Desktop

Verwenden Sie Docker Desktop mit aktivierten Windows-Containern:

docker compose -f deployments/docker-compose/ansible-windows/docker-compose.yml up

Räumen Sie anschließend auf mit:

docker compose -f deployments/docker-compose/ansible-windows/docker-compose.yml down

Weitere Details:

Docker Windows Ansible README

Windows unter Windows mit Hyper-V

Installieren Sie zuerst die Host-Abhängigkeiten:

sailwright.exe install

Für den Build benötigen Sie ein Windows-ISO. Sie können es manuell bei Microsoft herunterladen oder dieses Skript verwenden:

download_win_11.ps1

Details zum Build finden Sie hier:

Sobald die VM läuft, provisionieren Sie sie vom Repository-Stammverzeichnis aus:

sailwright.exe provision windows11 --arch amd64 --check
sailwright.exe provision windows11 --arch amd64

Legen Sie die WinRM-Zugangsdaten in der .env im Projektstamm oder in der Prozessumgebung fest:

HYPERV_WINDOWS_ANSIBLE_USER=Administrator
HYPERV_WINDOWS_ANSIBLE_PASSWORD=your-secure-password
# Optional (defaults shown):
HYPERV_WINDOWS_ANSIBLE_CONNECTION=winrm
HYPERV_WINDOWS_ANSIBLE_WINRM_TRANSPORT=basic
HYPERV_WINDOWS_ANSIBLE_PORT=5985

Optionale Überschreibungen der Shell-Pfade für den Windows/Cygwin-Wrapper:

$env:CYGWIN_BASH_PATH = "C:\tools\cygwin\bin\bash.exe"
# or, if you prefer setting the Cygwin terminal path:
$env:CYGWIN_TERMINAL_PATH = "C:\tools\cygwin\bin\mintty.exe"

Reihenfolge bei der Pfadauflösung für das Provisioning:

CYGWIN_BASH_PATH
CYGWIN_TERMINAL_PATH, wenn CYGWIN_BASH_PATH nicht gesetzt ist
Automatische Erkennung von C:\tools\cygwin\bin\bash.exe
Automatische Erkennung von C:\cygwin64\bin\bash.exe

Verweist CYGWIN_TERMINAL_PATH auf mintty.exe, löst das Provisioning den Pfad zur danebenliegenden bash.exe auf.

Workflows für macOS-Hosts

macOS unter macOS mit Tart

Verwenden Sie das mitgelieferte Skript:

./scripts/macos/test-ansible-macos.sh

Das Skript führt das Ansible-Playbook gegen eine temporäre Tart-VM aus. Tart-Projekt:

https://github.com/cirruslabs/tart

Standardmäßig nutzt Sailwright für den Ansible-Zugriff die Entwicklungs-Zugangsdaten des Tart-Images (admin / admin). Bei Bedarf überschreiben Sie sie in .env:

TART_MACOS_ANSIBLE_USER=admin
TART_MACOS_ANSIBLE_PASSWORD=admin

TART_MACOS_ANSIBLE_BECOME_PASSWORD entspricht standardmäßig TART_MACOS_ANSIBLE_PASSWORD, wenn es nicht gesetzt ist.

Räumen Sie anschließend auf mit:

tart delete sequoia-base

Windows unter macOS mit UTM

Installieren Sie zuerst die Host-Abhängigkeiten:

sailwright install

Erstellen und legen Sie die Windows-11-VM an:

# arm64 requires sudo to create a custom .iso file for automated installation.
# sudo rights are evaluated at runtime, so you can run the build command without sudo and it will ask for sudo rights only if needed.
arch=arm64 # or amd64
# sudo sailwright build windows11 --arch $arch --headless
sailwright build windows11 --arch $arch --headless
# `--headless` applies to `build`, not `create`.
sailwright create windows11 --arch $arch

Öffnen Sie UTM und starten Sie die angelegte VM.

Legen Sie die WinRM-Zugangsdaten in der .env im Projektstamm oder in der Prozessumgebung fest:

UTM_WINDOWS_ANSIBLE_USER=Administrator
UTM_WINDOWS_ANSIBLE_PASSWORD=your-secure-password
# Optional (defaults shown):
UTM_WINDOWS_ANSIBLE_CONNECTION=winrm
UTM_WINDOWS_ANSIBLE_WINRM_TRANSPORT=basic
UTM_WINDOWS_ANSIBLE_PORT=5985

Provisionieren Sie die VM vom Repository-Stammverzeichnis aus:

sailwright provision windows11 --arch $arch --check
sailwright provision windows11 --arch $arch

Der Wrapper ermittelt die IP-Adresse der VM automatisch aus der generierten UTM-Konfiguration und per arp -a und führt ansible-playbook mit einem Inline-Inventory-Ziel aus. Unter macOS setzt er für den Ansible-Prozess außerdem automatisch OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES.

Wenn Sie die ermittelte IP-Adresse manuell prüfen möchten:

bash ./deployments/utm/determine-vm-ip-address.sh --arch $arch --os windows11

Weiterführende Anleitung:

Windows Packer README

Neu erstellte Windows-Images installieren eine eigene WinRM-Firewallregel für TCP 5985 auf allen Netzwerkprofilen, sodass spätere Änderungen an der Netzwerkkarte oder am Netzwerkprofil die Erreichbarkeit nicht beeinträchtigen sollten. Bei älteren Images müssen Sie das Netzwerk eventuell noch auf Private umstellen oder eine entsprechende Firewallregel manuell ergänzen.

Ubuntu unter macOS mit UTM

Installieren Sie zuerst die Host-Abhängigkeiten:

sailwright install

Erstellen und legen Sie die Ubuntu-VM an:

arch=arm64 # or amd64
type=desktop # or server
sailwright build ubuntu --arch $arch --type $type
sailwright create ubuntu --arch $arch --type $type

Öffnen Sie UTM und starten Sie die angelegte VM.

Legen Sie die Ubuntu-SSH-Zugangsdaten in der .env im Projektstamm oder in der Prozessumgebung fest:

UTM_UBUNTU_ANSIBLE_USER=packer
UTM_UBUNTU_ANSIBLE_PASSWORD=P@ssw0rd!
UTM_UBUNTU_ANSIBLE_BECOME_PASSWORD=P@ssw0rd!
# Optional (defaults shown):
UTM_UBUNTU_ANSIBLE_CONNECTION=ssh
UTM_UBUNTU_ANSIBLE_SSH_COMMON_ARGS=-o StrictHostKeyChecking=no -o ServerAliveInterval=10 -o ServerAliveCountMax=3 -o ControlMaster=no -o ControlPersist=no
UTM_UBUNTU_ANSIBLE_SSH_TIMEOUT=120
UTM_UBUNTU_ANSIBLE_SSH_RETRIES=3

Provisionieren Sie die VM vom Repository-Stammverzeichnis aus:

sailwright provision ubuntu --type $type --arch $arch --check
sailwright provision ubuntu --type $type --arch $arch

Wenn Sie die ermittelte IP-Adresse manuell prüfen möchten:

bash ./deployments/utm/determine-vm-ip-address.sh --arch $arch --os "ubuntu-$type"