Debian 13 (Trixie) Post-Install and System Initialization

This README is a how-to guide with quick orientation.

The setup flow has two stages:

1. scripts/setup.sh performs the base system bootstrap and reboots.
2. scripts/post-setup.sh runs post-reboot tasks through ordered hooks.

Deep behavior details are in the reference documents linked at the end of this file.

Table of Contents

• Repository Layout
• Quick Orientation
• Prerequisites
• Stage One: Base Setup
• Stage Two: Post-Setup Dispatcher
• Extending Post-Setup
• Remote Bootstrap (No Clone)
• Trust and Integrity
• Verification
• Reference

Repository Layout

.
|-- .gitignore
|-- README.md
|-- docs/
|   `-- reference/
|       |-- README.md
|       |-- script-contracts.md
|       `-- troubleshooting.md
|-- post-setup/
|   `-- hooks/
|       |-- 10-install-onboot-update.sh
|       |-- 20-run-automount-disks.sh
|       |-- 30-install-docker.sh
|       |-- 40-install-labwc.sh
|       `-- 50-install-vscode.sh
|-- scripts/
|   |-- automount-disks.sh
|   |-- install-docker.sh
|   |-- install-labwc.sh
|   |-- onboot-update.sh
|   |-- post-setup.sh
|   `-- setup.sh
`-- systemd/
    `-- onboot-update.service

1. Quick Orientation

What this repository does:

• Configures Debian Trixie package sources and installs desktop-focused packages.
• Enables core services (bluetooth, seatd) and user group mappings.
• Installs and enables an on-boot update service.
• Configures on-demand automount for detected unmounted EXT4/NTFS disks.
• Installs Docker from the official Docker apt repository.

2. Prerequisites

• Debian 13 (Trixie).
• A non-root account with sudo privileges.
• Internet access for apt and package repositories.
• Commands run from the repository root.

Make scripts executable:

chmod +x scripts/*.sh post-setup/hooks/*.sh

3. Stage One: Base Setup

Prerequisites

• Run from your normal user account.
• Save your work before running, because the script reboots the machine.

Side Effects

• Repository and package state:
  • Rewrites /etc/apt/sources.list for Trixie repositories.
  • Runs apt-get update and apt-get full-upgrade -y.
  • Installs system packages and enables services.
• Boot and hardware configuration:
  • Disables btusb autosuspend, switches initramfs module policy to MODULES=dep, and rebuilds the current initramfs before rebooting.
  • Reboots automatically after a 5-second delay.
• User and group membership:
  • Adds the invoking sudo user to video, render, and seat groups.

scripts/setup.sh configures repositories, upgrades packages, installs core tooling, and configures services/users.

WARNING: this script is destructive and reboots the machine when it finishes.

Run:

sudo ./scripts/setup.sh

After reboot, log back in and continue with stage two.

4. Stage Two: Post-Setup Dispatcher

Prerequisites

• Stage one completed and the system has rebooted.
• Run from a local clone of this repository.
• Run through sudo from a non-root account.

Side Effects

• Service installation and systemd:
  • Installs onboot-update.sh to /usr/local/sbin/onboot-update.sh.
  • Installs onboot-update.service to /etc/systemd/system/onboot-update.service.
  • Reloads systemd and enables onboot-update.service.
  • Reloads systemd after automount changes are written so newly created or updated automount units are recognized.
• Disk automount configuration:
  • May add or update /etc/fstab entries for eligible EXT4/NTFS disks; EXT4 mount-root ownership is enforced for managed disks on every run, and NTFS entries map ownership with uid=/gid=.
  • Creates /etc/fstab.backup.<timestamp> before writing fstab changes.
• Docker installation:
  • Installs Docker Engine and plugins from Docker's official apt repository.
• labwc installation modes:
  • Prompts for labwc install mode (Debian package, latest source build, or docker-package), unless LABWC_INSTALL_MODE environment variable is set to skip prompt.
  • Docker-package mode builds a labwc .deb in a Debian container matching host VERSION_CODENAME (override with LABWC_DOCKER_IMAGE), then installs the resulting package on the host.
  • Docker-package mode checks out the latest labwc tag, reads meson.build to detect the required wlroots ABI name (wlroots-X.Y), and tries to install matching container package libwlroots-X.Y-dev.
  • If the matching wlroots dev package is unavailable in the container image, docker-package mode builds wlroots from source in-container from https://gitlab.freedesktop.org/wlroots/wlroots using ref X.Y (fallback X.Y.0), installs it, then continues the labwc package build.
  • Docker-package mode requires Docker CLI availability, a reachable Docker daemon, and network access for container apt operations plus Git access to https://github.com/labwc/labwc and https://gitlab.freedesktop.org/wlroots/wlroots.
  • For restricted networks, set LABWC_DOCKER_IMAGE to an internally reachable Debian-compatible mirror image before running post-setup.
  • Source mode installs build dependencies transiently, then removes only newly-added packages via apt-mark auto (preserves pre-existing manual package installs).
  • Source mode builds labwc with xwayland disabled and may let Meson download wlroots automatically when the required system version is unavailable.
• labwc configuration:
  • Deploys labwc config files to ${XDG_CONFIG_HOME:-$HOME/.config}/labwc: uses binary selection to copy from repo .config/labwc if it contains any candidate files; otherwise attempts /usr/share/doc/labwc as fallback. Never overwrites existing files.

scripts/post-setup.sh runs ordered hooks and stops on the first failure.

Current core hooks:

• post-setup/hooks/10-install-onboot-update.sh — Install and enable the on-boot update service.
• post-setup/hooks/20-run-automount-disks.sh — Run disk automount configuration.
• post-setup/hooks/30-install-docker.sh — Install Docker from the official Docker apt repository.
• post-setup/hooks/40-install-labwc.sh — Install labwc (package, source, or docker-package mode, chosen interactively or by environment variable).
• post-setup/hooks/50-install-vscode.sh — Install VS Code Insiders from Microsoft's apt repository.

Run:

sudo ./scripts/post-setup.sh

5. Extending Post-Setup

The dispatcher uses a hybrid model:

• Core ordered hooks in post-setup/hooks/ (versioned in this repo).
• Optional local hooks in /etc/post-setup.d/*.sh (machine-local extensions).

Add a local extension hook with an ordering prefix:

sudo install -d /etc/post-setup.d
sudo tee /etc/post-setup.d/30-example.sh > /dev/null <<'EOF'
#!/usr/bin/env bash
set -Eeuo pipefail
echo "Running custom post-setup extension"
EOF
sudo chmod +x /etc/post-setup.d/30-example.sh

Rerun dispatcher:

sudo ./scripts/post-setup.sh

6. Remote Bootstrap (No Clone)

Only self-contained scripts should be run remotely. Each command block below shows what it will execute:

Bootstrap the base system (stage one only): Downloads and runs the main setup script, which configures repositories, installs core packages, applies the boot-time Bluetooth and initramfs fixes, and reboots.

curl -sSL https://raw.githubusercontent.com/d3bvstack/System-init/master/scripts/setup.sh | sudo bash

Configure disk automounting only: Downloads and runs the automount script, which detects eligible EXT4/NTFS disks, requires findmnt and systemd, and adds or updates automount entries in /etc/fstab.

curl -sSL https://raw.githubusercontent.com/d3bvstack/System-init/master/scripts/automount-disks.sh | sudo bash

Install Docker from the official apt repository: Downloads the Docker installer, reviews it locally, and then runs it with root privileges.

curl -sSLo /tmp/install-docker.sh https://raw.githubusercontent.com/d3bvstack/System-init/master/scripts/install-docker.sh
less /tmp/install-docker.sh
sudo bash /tmp/install-docker.sh

Install and enable the on-boot update service only: Downloads the update script and systemd unit, installs them to the correct locations, reloads systemd, and enables the service.

cd "$(mktemp -d)"
curl -sSLo onboot-update.sh https://raw.githubusercontent.com/d3bvstack/System-init/master/scripts/onboot-update.sh
curl -sSLo onboot-update.service https://raw.githubusercontent.com/d3bvstack/System-init/master/systemd/onboot-update.service
sudo install -Dm755 onboot-update.sh /usr/local/sbin/onboot-update.sh
sudo install -Dm644 onboot-update.service /etc/systemd/system/onboot-update.service
sudo systemctl daemon-reload
sudo systemctl enable onboot-update.service

Not supported as standalone remote execution (requires repository layout on disk):

• scripts/post-setup.sh
• post-setup/hooks/*.sh

7. Trust and Integrity

Piping remote scripts into a privileged shell is high risk. Prefer download-review-run:

curl -sSLo /tmp/setup.sh https://raw.githubusercontent.com/d3bvstack/System-init/master/scripts/setup.sh
less /tmp/setup.sh
sudo bash /tmp/setup.sh

For unattended automation, pin to an immutable ref (tag or commit SHA) and verify content before execution.

8. Verification

Check stage outcomes:

systemctl --user status pipewire
code-insiders --version
systemctl status onboot-update.service
grep -E 'x-systemd\.automount' /etc/fstab

Optional updater smoke test:

sudo systemctl start onboot-update.service
sudo journalctl -u onboot-update.service -n 50 --no-pager

Optional Docker verification:

sudo systemctl status docker --no-pager
sudo docker run hello-world

9. Reference

For in-depth technical details, see the reference documentation:

• Reference Index: Overview of all available technical docs.
• Script Contracts: Inputs, required environment, side effects, and idempotency for each script.
• Failure Modes & Troubleshooting: Common errors, recovery steps, and diagnostics for each stage.