README.md

Reference Documentation Index

Welcome to the technical reference for this repository. Use this index to quickly find the information you need.

Finding Answers by Task

"I want to know what a script does"

See the Script Contracts reference, which documents:

• Invocation mode and arguments
• Required environment and dependencies
• Side effects (what the script changes on the system)
• Idempotency characteristics (safe to re-run?)

Quick links:

• scripts/setup.sh — Base system bootstrap and reboot
• scripts/post-setup.sh — Post-reboot dispatcher
• scripts/onboot-update.sh — 12-hour debounced updater
• scripts/automount-disks.sh — Detect and automount eligible EXT4/NTFS disks
• scripts/install-docker.sh — Install Docker from the official apt repository
• scripts/install-vscode.sh — Install VS Code Insiders from Microsoft's apt repository
• scripts/install-labwc.sh — Install labwc from package, source, or Docker-built package and deploy config
• systemd/onboot-update.service — Service unit and hardening policy

Hooks:

• post-setup/hooks/10-install-onboot-update.sh — Install updater hook
• post-setup/hooks/20-run-automount-disks.sh — Run automount hook
• post-setup/hooks/30-install-docker.sh — Run Docker install hook
• post-setup/hooks/40-install-labwc.sh — Run labwc install hook
• post-setup/hooks/50-install-vscode.sh — Run VS Code Insiders install hook

"A script failed. How do I fix it?"

See the Failure Modes & Troubleshooting reference, organized by stage:

Stage 1 (Base Setup):

• apt update/upgrade failures
• seat group already exists
• boot-time fixes do not rebuild

Stage 2 (Post-Setup Dispatcher):

• post-setup dispatcher rejects execution context
• missing hook/source files
• local extension hook failures

Disk Automounting:

• no disks configured
• NTFS disks skipped
• legacy NTFS entry still uses users
• mount or ownership failures
• mount path exists but is not a directory
• generated /etc/fstab content fails validation
• restore from fstab backup

Docker Installation:

• install-docker rejects execution context or missing codename
• repository setup or package install fails
• Docker daemon is not running
• hello-world verification fails

VS Code Installation:

• repository setup or install fails

Labwc Installation:

• install-labwc rejects execution context
• package mode install fails
• source mode build fails
• no config files copied
• invalid LABWC_INSTALL_MODE
• LABWC_DOCKER_IMAGE is set but empty
• git tag resolution fails
• Docker-package build completes but no .deb is emitted
• build cleanup issues

On-Boot Updater:

• service not running at boot
• service skips due to debounce

Diagnostics Checklist — What to include when reporting issues.

Available Documents

Document	Purpose	When to Use
script-contracts.md	Technical specification for each script	Understanding what a script does, required inputs, side effects, or whether it's idempotent
troubleshooting.md	Error diagnosis and recovery procedures	Fixing failures, understanding error messages, or recovering from partial completion

Quick Reference: By Script

Script	Contract	Failures	Stage
scripts/setup.sh	link	link	1
scripts/post-setup.sh	link	link	2
post-setup/hooks/10-install-onboot-update.sh	link		2
post-setup/hooks/20-run-automount-disks.sh	link		2
post-setup/hooks/30-install-docker.sh	link		2
post-setup/hooks/40-install-labwc.sh	link		2
post-setup/hooks/50-install-vscode.sh	link		2
scripts/automount-disks.sh	link	link	2
scripts/install-docker.sh	link	link	2
scripts/install-vscode.sh	link		2
scripts/install-labwc.sh	link	link	2
scripts/onboot-update.sh	link	link	boot
systemd/onboot-update.service	link	link	boot