debian-resources/Debian Deployment Guide.md

Debian Deployment Guide

This step-by-step guide outlines the process of recreating the testunit-zalpha system, a Debian testing-based environment tailored for development, virtualization, container management, and media hosting.

1. Initial OS Installation

1. Gather the Debian Testing (forky/sid) installer ISO.
2. Install with the following partitioning scheme:
   • EFI System Partition (/boot/efi) - ~1GB, vfat
   • Root Partition (/) - ~200GB, btrfs
   • Swap Partition ([SWAP]) - ~5GB
3. During installation, configure the root filesystem to use zstd:3 compression. You may need to edit /etc/fstab post-install to add the compress-force=zstd:3 option to the root subvolume (@rootfs).

2. Post-Install User & Groups

After booting into the initial system, add your primary user to the necessary groups for administration and hardware access:

sudo usermod -aG sudo,adm,docker,dialout,plugdev,netdev,systemd-journal $USER

If you prefer passwordless sudo for testing environments:

sudo visudo
# Add: username ALL=(ALL) NOPASSWD: ALL
sudo passwd -d $USER

3. Repositories & Pinning

3.1 Sources List

Configure /etc/apt/sources.list for testing, stable, and unstable:

deb http://debian.osuosl.org/debian/ testing main non-free-firmware contrib non-free
deb http://security.debian.org/debian-security/ testing-security main non-free-firmware contrib non-free
deb http://debian.osuosl.org/debian/ testing-updates main non-free-firmware contrib non-free
deb http://debian.osuosl.org/debian/ stable main non-free-firmware contrib non-free
deb http://debian.osuosl.org/debian/ sid main non-free-firmware contrib non-free

3.2 Add Third-Party Repositories

Docker:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: trixie
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Thorium Browser:

sudo wget --no-hsts -P /etc/apt/sources.list.d/ http://dl.thorium.rocks/debian/dists/stable/thorium.list

3.3 APT Pinning

Create /etc/apt/preferences.d/99-debian to prioritize testing over unstable:

Package: *
Pin: release a=testing
Pin-Priority: 600

Package: *
Pin: release a=testing-updates
Pin-Priority: 700

Package: *
Pin: release a=unstable
Pin-Priority: 100

Update apt sources:

sudo apt update

4. Installed Packages

4.1 Base Utilities & Desktop

sudo apt install ncdu btop tmux fish fail2ban ripgrep rsync btrfs-progs htop mosh p7zip iperf3 fd-find mc kitty-terminfo curl git bat unrar rclone rar gocryptfs cryfs securefs wireguard lzop lz4 w3m w3m-img elinks picom dosbox task-cinnamon-desktop
sudo apt install -t sid yt-dlp

Remove unnecessary defaults:

sudo apt remove brasero thunderbird libreoffice-core
rm ~/.local/share/keyrings/login.keyring 

4.2 Docker Deployment

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Configure Docker Daemon (/etc/docker/daemon.json):

{
  "default-address-pools": [
    {"base": "172.17.0.0/12", "size": 20},
    {"base": "192.168.0.0/16", "size": 24}
  ]
}

Restart Docker: sudo systemctl restart docker

4.3 Development & Cross-Compilation

# Add foreign architecture for cross-compiling
sudo dpkg --add-architecture armhf
sudo apt update

# Install build tools
sudo apt install build-essential pkg-config cmake make autoconf automake libtool gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf lib32stdc++6 lib32gcc-s1 protobuf-compiler libprotobuf-dev libncurses-dev zlib1g-dev:armhf libssl-dev:armhf libncurses-dev:armhf libzstd-dev:armhf libsdl2-dev libsdl2-ttf-dev libsdl2-image-dev cc65 fceux zstd git php golang npm nodejs xxhash python3-xxhash pipx

5. System Configuration

5.1 Dockge Installation

sudo mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge
curl https://dockge.kuma.pet/compose.yaml --output compose.yaml
sudo docker compose up -d

5.2 Network Mounts (fstab)

Edit /etc/fstab to add network file systems and shared folders (adjust IPs as needed):

# 9p Virtio Host Folder
Public-sapient     /home/user/Public  9p  trans=virtio,version=9p2000.L,msize=104857600,uid=1000,gid=1000,access=client,cache=none,dirsync,x-systemd.automount,nofail  0 0

# NFS Hive Storage
10.8.0.10:/storage /mnt/hive       nfs    defaults,_netdev,x-systemd.automount,noatime   0 0

Create mount points:

sudo mkdir -p /mnt/hive

5.3 WireGuard VPN (wg0)

Generate keys and create /etc/wireguard/wg0.conf:

[Interface]
Address = 10.8.0.50/24
ListenPort = 33303
PrivateKey = <generated_private_key>

[Peer]
PublicKey = <central_server_public_key>
Endpoint = 82.29.54.2:51820
AllowedIPs = 10.8.0.0/24
PersistentKeepalive = 25

Enable and start:

sudo systemctl enable --now wg-quick@wg0

5.4 Swap Configuration

Install and configure zram-tools to enable the 4GB zram0 swap device, supplementing the partition swap.

6. Final Steps

1. Configure picom as your compositor of choice in the session startup.
2. Verify SSH configuration (/etc/ssh/sshd_config) has KbdInteractiveAuthentication no and UsePAM yes.
3. Migrate Dockge stacks into /opt/stacks and start them using Dockge UI (http://<ip>:5001).