mirror of
https://github.com/stornic56/debianito-post-install.git
synced 2026-10-31 13:08:06 +00:00
Recovered 70 prior commits from Gitea mirror and resolved divergent history using --allow-unrelated-histories. Integrated 16 recent local commits via patch. Applied targeted technical fixes: added explicit bash shell declaration in shellcheck YAML configuration (commit 693caff) and targeted SC2120 disables in modules/utils.sh (commit 3614b56). All verifications passed: shellcheck compliance, bash syntax check (bash -n), and BATS test suite passing cleanly. Symmetrically synchronized repository state across GitHub and Gitea.
This commit is contained in:
stornic56
+55
-43
@@ -1,4 +1,4 @@
|
||||
# Debianito — Quick Start Visual Guide
|
||||
# Debianito: Quick Start Visual Guide
|
||||
|
||||
> **Scope:** Fresh Debian 11 / 12 / 13 installation → fully configured desktop in ~15-20 minutes.
|
||||
> **Prerequisites:** Normal user with `sudo` access. Do **not** run the script as root.
|
||||
@@ -18,13 +18,25 @@ The script automatically checks for `whiptail` and `lsb-release`, installs them
|
||||
|
||||
> 
|
||||
|
||||
With no flags the script runs interactively. Three flags change that (full table in the [README](../README.md#command-line-usage)):
|
||||
|
||||
```bash
|
||||
./debianito.sh --yes # auto-confirm prompts; menus still display
|
||||
./debianito.sh --yes --allow-destructive # also unblock branch migration
|
||||
./debianito.sh --help # show usage and exit
|
||||
```
|
||||
|
||||
`--yes` auto-confirms prompts, but the menus still display and still need arrow keys and ENTER. By itself it does not reach branch migration (menu `4 [ADVANCED] Upgrade system branch`): that operation can leave the system unbootable, so the script reports that `--allow-destructive` is required. `DEBIANITO_PROFILE=1 ./debianito.sh` stamps each boot step to stderr with a timestamp, which makes before/after comparisons possible. An unknown option exits with status 2.
|
||||
|
||||
Package installs are batched behind a single confirmation: the script lists what it is about to install (the first 15 package names, plus a count of the rest) and asks you to proceed. With `--yes` these confirmations are accepted automatically.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Order
|
||||
|
||||
Each step builds on the previous one. Steps 1-5 + 10 are the essential path; 6-9 are optional.
|
||||
Each step builds on the previous one. Steps 1-6 are the essential path; steps 7-10 are optional.
|
||||
|
||||
### Step 1 — Know Your System
|
||||
### Step 1: Know Your System
|
||||
|
||||
**Menu:** `1 System Information`
|
||||
|
||||
@@ -39,11 +51,11 @@ You will see:
|
||||
- Storage topology (NVMe / SSD / HDD / USB-SD)
|
||||
- Display server (Wayland / X11 / tty) and desktop environment
|
||||
|
||||
Remember the **GPU line** (Intel / AMD / NVIDIA) and any **WiFi chipset** — you will need them in Steps 4-5.
|
||||
Remember the **WiFi chipset** for the firmware mapping in Step 5, and the **GPU line** (Intel / AMD / NVIDIA) for the drivers in Step 6.
|
||||
|
||||
>  System Information dialog with hardware summary.
|
||||
|
||||
### Step 2 — Fix Permissions Early (Optional but Recommended)
|
||||
### Step 2: Fix Permissions Early (Optional but Recommended)
|
||||
|
||||
**Menu:** `2 User Privileges & Feedback`
|
||||
|
||||
@@ -54,12 +66,12 @@ A sub-menu with four toggles:
|
||||
| Sudo group membership | `usermod -aG sudo $USER` | Fresh install where the first user is not in `sudo` |
|
||||
| Passwordless sudo | Creates `/etc/sudoers.d/$USER-nopasswd` with `NOPASSWD` for `apt`, `systemctl`, etc. | Lab / personal machine; skip on shared systems |
|
||||
| Repair home ownership | `chown -R $USER:$USER $HOME` | Home files owned by root after a mishandled `sudo` |
|
||||
| Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` — shows `****` while typing | **Enable now** to avoid typos during the many installs that follow |
|
||||
| Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` (typing then shows `****`) | **Enable now** to avoid typos during the many installs that follow |
|
||||
|
||||
>  User Privileges & Feedback menu.
|
||||
>  Confirmation dialog for "Sudo Password Feedback" with asterisk preview.
|
||||
|
||||
### Step 3 — System Preferences (Optional)
|
||||
### Step 3: System Preferences (Optional)
|
||||
|
||||
**Menu:** `3 System Preferences`
|
||||
|
||||
@@ -70,13 +82,13 @@ A sub-menu with four toggles:
|
||||
4 Back to main menu
|
||||
```
|
||||
|
||||
- **Date, Time & Timezone** — Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update` — a wrong clock breaks GPG verification.
|
||||
- **Language, Locales & Keyboard** — Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`.
|
||||
- **Audio & Sound Stack** — Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [System Preferences](system_prefs.md).
|
||||
- **Date, Time & Timezone**: Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update`: a wrong clock breaks GPG verification.
|
||||
- **Language, Locales & Keyboard**: Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`.
|
||||
- **Audio & Sound Stack**: Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [System Preferences](system_prefs.md).
|
||||
|
||||
>  System Preferences menu.
|
||||
|
||||
### Step 4 — Configure Repositories (Required)
|
||||
### Step 4: Configure Repositories (Required)
|
||||
|
||||
**Menu:** `4 Configure Repositories`
|
||||
|
||||
@@ -88,32 +100,32 @@ A sub-menu with four toggles:
|
||||
5 Back to main menu
|
||||
```
|
||||
|
||||
1. Choose **1. Enable Contrib & Non-Free** — adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback.
|
||||
2. Choose **3. Setup/Update Backports** — answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [Configure Repositories](repos_config.md).
|
||||
1. Choose **1. Enable Contrib & Non-Free**: adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback.
|
||||
2. Choose **3. Setup/Update Backports**: answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [Configure Repositories](repos_config.md).
|
||||
|
||||
⚠️ Without `non-free` and `contrib`, Steps 5 and 8 will fail. Do not skip.
|
||||
|
||||
>  Repositories menu.
|
||||
>  Backports confirmation dialog.
|
||||
|
||||
### Step 5 — Install Firmware & Wireless Drivers
|
||||
### Step 5: Install Firmware & Wireless Drivers
|
||||
|
||||
**Menu:** `5 Firmware, Wireless & Bluetooth`
|
||||
|
||||
The script:
|
||||
|
||||
- Scans **all** network hardware (PCI `lspci -nn` + USB `lsusb`, filtered for Realtek/Intel/Mediatek/Atheros/Qualcomm) and Bluetooth controllers
|
||||
- Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc` — plus `firmware-linux-nonfree` as the base meta-package
|
||||
- Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc`, plus `firmware-linux-nonfree` as the base meta-package
|
||||
- Builds a plan showing detected controllers and planned packages, including Bluetooth handling (KDE → `bluedevil`, XFCE → `blueman`, GNOME → built-in, plus `pipewire-pulse`/`wireplumber` if PipeWire is active)
|
||||
- Asks for confirmation before installing; offers Stable vs Backports for the base firmware
|
||||
|
||||
Accept the plan it shows — it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`.
|
||||
Accept the plan it shows: it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`.
|
||||
|
||||
⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first — the driver needs a fresh load.
|
||||
⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first: the driver needs a fresh load.
|
||||
|
||||
>  Firmware plan dialog with hardware + package list.
|
||||
|
||||
### Step 6 — Install Graphics Drivers
|
||||
### Step 6: Install Graphics Drivers
|
||||
|
||||
**Menu:** `6 Graphics Drivers & Mesa Stack`
|
||||
|
||||
@@ -124,11 +136,11 @@ Whiptail radiolist with two options:
|
||||
2 NVIDIA Drivers
|
||||
```
|
||||
|
||||
#### Path A — Radeon/Intel Mesa
|
||||
#### Path A: Radeon/Intel Mesa
|
||||
|
||||
Shows a plan with detected GPUs (`Intel firmware + intel-media-va-driver-non-free` or `i965-va-driver-shaders` for Gen7-, `firmware-amd-graphics` for AMD, plus `Mesa Vulkan/OpenGL/VA-API`). Offers legacy AMD GCN 1.0/1.1 migration to `amdgpu` via GRUB params (`radeon.si_support=0 ... amdgpu.si_support=1`). Installs Mesa from Backports or Stable (`_install_mesa_backports`), verifies `mesa-vulkan-drivers`, and offers vendor-specific telemetry (`radeontop`, `intel-gpu-tools`, `vainfo`).
|
||||
|
||||
#### Path B — NVIDIA Drivers
|
||||
#### Path B: NVIDIA Drivers
|
||||
|
||||
Shows detected NVIDIA GPUs and a two-stage menu:
|
||||
|
||||
@@ -137,13 +149,13 @@ Shows detected NVIDIA GPUs and a two-stage menu:
|
||||
- Bookworm: `v535` (Recommended) or `v470` (Kepler legacy via `nvidia-tesla-470-driver`)
|
||||
- Trixie: `v550` (Debian stable, Recommended), `v590` or `v595` (NVIDIA CUDA Repo with `cuda-keyring` + `nvidia-open` + `firmware-nvidia-gsp`)
|
||||
|
||||
The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility — e.g., Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message.
|
||||
The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility. For example, Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message.
|
||||
|
||||
>  GPU type selector (Radeon/Intel vs NVIDIA).
|
||||
|
||||
After installation, **reboot** before testing. NVIDIA drivers need a fresh kernel load.
|
||||
|
||||
### Step 7 — Kernel Configuration (Optional)
|
||||
### Step 7: Kernel Configuration (Optional)
|
||||
|
||||
**Menu:** `7 Kernel`
|
||||
|
||||
@@ -155,17 +167,17 @@ cloud Install linux-image-cloud-amd64
|
||||
back Return to main menu
|
||||
```
|
||||
|
||||
- **Stable** — default Debian kernel (6.12 LTS on Trixie).
|
||||
- **Backports** — only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc.
|
||||
- **RT** — Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT).
|
||||
- **Cloud** — minimal kernel for VMs/containers (`linux-image-cloud-amd64`).
|
||||
- **Stable**: default Debian kernel (6.12 LTS on Trixie).
|
||||
- **Backports**: only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc.
|
||||
- **RT**: Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT).
|
||||
- **Cloud**: minimal kernel for VMs/containers (`linux-image-cloud-amd64`).
|
||||
|
||||
Each variant installs the matching `linux-headers-*` package atomically (`sudo apt install -y [-t trixie-backports] linux-image-* linux-headers-*`). The script warns about DKMS recompilation if NVIDIA is present.
|
||||
|
||||
>  — Kernel menu with four variants.
|
||||
>  Kernel menu with four variants.
|
||||
> See [kernel](kernel.md) for backports rationale and bootloader details.
|
||||
|
||||
### Step 8 — Gaming Setup (Optional)
|
||||
### Step 8: Gaming Setup (Optional)
|
||||
|
||||
**Menu:** `8 Gaming Setup`
|
||||
|
||||
@@ -194,7 +206,7 @@ A single checklist with all options:
|
||||
>  Gaming checklist with i386 + Steam + MangoHud checked.
|
||||
> See [gaming](gaming.md) and [retroarch](retroarch.md).
|
||||
|
||||
### Step 9 — ZRAM Compressed Swap (Optional)
|
||||
### Step 9: ZRAM Compressed Swap (Optional)
|
||||
|
||||
**Menu:** `9 ZRAM`
|
||||
|
||||
@@ -205,15 +217,15 @@ A single checklist with all options:
|
||||
4 Back to main menu
|
||||
```
|
||||
|
||||
- **View** — Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output.
|
||||
- **Create / Reconfigure** — Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10).
|
||||
- **Remove** — `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`.
|
||||
- **View**: Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output.
|
||||
- **Create / Reconfigure**: Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10).
|
||||
- **Remove**: `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`.
|
||||
|
||||
>  Algorithm choice (lz4 vs zstd).
|
||||
>  `zramctl` status output in whiptail.
|
||||
> See [zram](zram.md).
|
||||
|
||||
### Step 10 — Swap Management (Optional)
|
||||
### Step 10: Swap Management (Optional)
|
||||
|
||||
**Menu:** `10 Swap Management`
|
||||
|
||||
@@ -234,7 +246,7 @@ A single checklist with all options:
|
||||
>  Swap status.
|
||||
> See [swap](swap.md).
|
||||
|
||||
### Step 11 — Install Programs and Software
|
||||
### Step 11: Install Programs and Software
|
||||
|
||||
**Menu:** `11 Install Programs and Software` → `0 Essential Pack`
|
||||
|
||||
@@ -261,17 +273,17 @@ After this, browse the other categories as needed:
|
||||
>  Category menu with 0-14 options.
|
||||
>  Essential Pack confirmation.
|
||||
|
||||
### Step 12 — Boot Rescue
|
||||
### Step 12: Boot Rescue
|
||||
|
||||
**Menu:** `12 Boot Rescue + GRUB`
|
||||
|
||||
- **GRUB boot menu settings** — 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback.
|
||||
- **UEFI Secure Boot repair** — reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`).
|
||||
- **Initramfs regeneration** — `update-initramfs -u -k all || true`.
|
||||
- **GRUB boot menu settings**: 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback.
|
||||
- **UEFI Secure Boot repair**: reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`).
|
||||
- **Initramfs regeneration**: `update-initramfs -u -k all || true`.
|
||||
|
||||
> See [boot](boot.md).
|
||||
|
||||
### Step 13 — Desktop & Display
|
||||
### Step 13: Desktop & Display
|
||||
|
||||
**Menu:** `13 Desktop & Display`
|
||||
|
||||
@@ -281,8 +293,8 @@ After this, browse the other categories as needed:
|
||||
3 Back to main menu
|
||||
```
|
||||
|
||||
- **Desktop Environment** — pick one of **XFCE** (full / minimal / Wayland `labwc` on Trixie / custom checklist), **LXDE** (full / core), **GNOME** (full / core) or **KDE Plasma** (full / minimal). Each environment installs from its own module in `modules/desktops/` (lazy-loaded). XFCE installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group; GNOME/KDE preseed the display manager while keeping any already-configured one as default. After the install, the script offers the PipeWire audio stack if none is present.
|
||||
- **Display Manager** — LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet — manual `/etc/greetd/config.toml` required).
|
||||
- **Desktop Environment**: pick one of **XFCE** (full / minimal / Wayland `labwc` on Trixie / custom checklist), **LXDE** (full / core), **GNOME** (full / core) or **KDE Plasma** (full / minimal). Each environment installs from its own module in `modules/desktops/` (lazy-loaded). XFCE installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group; GNOME/KDE preseed the display manager while keeping any already-configured one as default. After the install, the script offers the PipeWire audio stack if none is present.
|
||||
- **Display Manager**: LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet; manual `/etc/greetd/config.toml` required).
|
||||
|
||||
> See [Desktop & Display](desktops_display.md).
|
||||
|
||||
@@ -301,7 +313,7 @@ After this, browse the other categories as needed:
|
||||
systemctl status bluetooth # Bluetooth active?
|
||||
```
|
||||
|
||||
3. For gaming, enable `i386` was handled — verify with `dpkg --print-foreign-architectures | grep i386`.
|
||||
3. For gaming, the script adds the `i386` architecture when you check `steam`, `lutris` or `i386`; verify with `dpkg --print-foreign-architectures | grep i386`.
|
||||
|
||||
---
|
||||
|
||||
@@ -313,6 +325,6 @@ After this, browse the other categories as needed:
|
||||
| **Black screen after NVIDIA + Wayland (GNOME/GDM3)** | At login, select *GNOME on Xorg* (gear icon) or disable Wayland: `sudo nano /etc/gdm3/daemon.conf` → `WaylandEnable=false`. The script only warns about Debian bug #1109409, it does not force X11. |
|
||||
| **GRUB menu hidden and cannot enter** | Hold `ESC` immediately after power-on. Or boot a live USB, `chroot`, and run `12 Boot Rescue → GRUB boot menu settings → Show 5 seconds`. |
|
||||
| **Steam fails to start** | Verify `i386` is enabled: `dpkg --print-foreign-architectures`. Check `contrib` is in `/etc/apt/sources.list`. Re-run `8 Gaming Setup` and ensure the checklist had `i386` + `steam` checked. |
|
||||
| **greetd installed but cannot log in** | This is expected — you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. |
|
||||
| **greetd installed but cannot log in** | This is expected: you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. |
|
||||
| **Bluetooth tray icon missing** | Reboot or `systemctl restart bluetooth`. Ensure `bluez`, `bluedevil` (KDE) or `blueman` (XFCE) is installed. For PipeWire, check `systemctl --user status pipewire pipewire-pulse wireplumber`. |
|
||||
| **PipeWire crackling / no Bluetooth Hi-Res codec** | Re-run `3 System Preferences → Audio & Sound → PipeWire Audio Stack`. Verify `libldacbt-*`, `libopenaptx0`, `libfdk-aac2t64` are installed (`dpkg -l \| grep -E 'ldac\|aptx\|fdk'`). |
|
||||
|
||||
Reference in New Issue
Block a user