ubuntu-post-install/README.md

ubuntu-post-install

Modular post-install system for Ubuntu servers. One repo, one entry point, install exactly what you need — interactively or by name.

Quick start on a fresh box

Public repo — paste on any new box:

curl -fsSL https://raw.githubusercontent.com/outis1one/ubuntu-post-install/main/bootstrap.sh | sudo bash

USB thumb drive — works for public or private repos:

Prepare the USB once on any machine (no git required):

1. Go to the repo on GitHub → green Code button → Download ZIP
2. Unzip it — you'll get a folder called ubuntu-post-install-main
3. Copy that folder to your USB drive

On every new box:

1. Plug in the USB — it opens in the file manager
2. Navigate into the ubuntu-post-install-main folder
3. Either:
   • Right-click inside the folder → Open in Terminal → type bash bootstrap.sh
   • Or double-click bootstrap.sh → if prompted, choose Run in Terminal

The script asks for your password if needed. It detects it is running from inside the repo, copies everything to ~/ubuntu-post-install, then launches the wizard — the USB can be unplugged once setup starts.

Private repo — PAT (alternative):

sudo bash bootstrap.sh --pat ghp_xxxxxxxxxxxxxxxxxxxx

Use a fine-grained read-only PAT scoped to just this repo (Contents: Read). The PAT is stripped from the stored remote URL after cloning.

Usage

sudo ./setup.sh                        # interactive wizard
sudo ./setup.sh caddy immich           # install specific services
sudo ./setup.sh configure              # set site defaults (timezone, domain, Caddy network)
./setup.sh --list                      # list all services grouped by category
sudo ./setup.sh --dry-run immich       # preview without making changes
sudo ./setup.sh --unattended base      # non-interactive, use defaults

What the wizard does

First run:

1. Installs essential CLI packages (see Base packages below)
2. Checks for Docker CE + Compose plugin; prompts to install if missing
3. Offers to set site defaults — timezone, base domain, Caddy Docker network — so every service picks them up automatically instead of asking each time
4. Offers to install Caddy (the reverse proxy most services use)
5. Drops into a category menu — pick a group, tick services, install, repeat

Re-run: skips steps 1–2 (already done), goes straight to the menu.

Site defaults are saved to ~/docker/.config and pre-fill every service prompt. Update them any time with sudo ./setup.sh configure.

Services

Group	Services
base	base — net-tools, ncdu, git, curl, wget, htop, tree, zip/unzip, ca-certificates, gnupg, jq, rsync; glow (terminal markdown reader, Charm apt repo)
homelab	caddy, crowdsec, authelia, homeassistant
utilities	actualbudget, ddclient, filebrowser, fmd, magicmirror, mealie, meshcentral, ntfy, portainer, traccar, uptimekuma, watchtower, wg-easy
media	arm, audiobookshelf, emby, immich, jellyfin, lyrion
cameras	frigate, frigate-audio, frigate-notify, sky-cam
gaming	js99er, minecraft, wolf, wolf-pair
extras	linux-to-sync, silent-send, sync-cc
backup	backup — Kopia (encrypted, dedup, scheduled)

Run ./setup.sh --list to see descriptions.

Backup

The backup service (under the backup group) sets up Kopia — but you are not limited to it. Below is a guide to every backup strategy in this repo, with advice on when to reach for each one.

---

Kopia — the built-in backup service

What it does: block-level deduplication + zstd compression + AES-256 encryption, scheduled automatically via a systemd timer (cron fallback). Each run snapshots configured paths and retains versions according to a policy (latest N, daily, weekly, monthly). An optional sync-to step mirrors the whole encrypted repository to another computer or a cloud bucket (SFTP, Backblaze B2, S3, rclone).

Install: sudo ./setup.sh backup

When to use: files that change constantly — Minecraft region files, game saves, Steam Proton prefixes, Docker config volumes. Every changed block is stored once; identical blocks across snapshots share storage. Kopia is the right default for homelab data that changes on every write.

---

Borg Backup

What it is: borgbackup — chunk-based deduplication + lz4/zstd/zlib compression + AES-CTR encryption. Mature, battle-tested, wide ecosystem (Borgmatic for YAML-driven automation, Vorta for a GUI).

sudo apt install borgbackup

# initialise a repo
borg init --encryption=repokey /backups/borg-repo

# take a snapshot
borg create --stats --progress /backups/borg-repo::'{hostname}-{now}' ~/docker

# list snapshots
borg list /backups/borg-repo

# restore
borg extract /backups/borg-repo::snapshot-name

When to use: same class of problem as Kopia — frequently-changing files where deduplication pays off. Choose Borg over Kopia if you prefer its mature ecosystem, Borgmatic config files, or need to share a repo across multiple machines. Both are excellent; pick the one whose tooling you prefer.

---

rsync — plain mirror (no versioning)

What it is: rsync -av --delete SOURCE/ DEST/ — fast one-way mirror. --delete removes files in DEST that no longer exist in SOURCE. The destination is a plain readable copy of the source; no special tool needed to browse or restore.

rsync -av --delete /source/media/ /backups/media/

When to use: files that rarely or never change — media libraries, ROM collections, game installs you could re-download but prefer to keep locally. You just need a copy, not versioning. rsync is lightweight, transparent, and the destination needs no special format.

Not suitable for: files that change often, because one bad --delete run (source corruption, accidental deletion) immediately destroys the only copy in the destination.

---

rsync --link-dest — versioned snapshots with original structure

What it is: each backup run creates a new dated directory. Unchanged files are hard-linked from the previous backup rather than copied, so unchanged files cost no extra disk space. Every dated directory looks like a complete independent snapshot of the source — original folder structure preserved, no rsnapshot-style naming convention.

#!/bin/bash
DEST=/backups/snapshots
PREV="$DEST/$(ls -1 "$DEST" | tail -1)"  # most recent snapshot
TODAY="$DEST/$(date +%F)"

rsync -av --delete --link-dest="$PREV" /source/ "$TODAY/"

Run this daily (via cron or a systemd timer) and you get:

/backups/snapshots/
  2024-01-13/    ← full copy (first run)
  2024-01-14/    ← only changed files stored; rest are hard links
  2024-01-15/    ← same

If yesterday's run with --delete removed everything from the source (accidental wipe, filesystem corruption), today's snapshot will also be empty — but 2024-01-14/ and 2024-01-13/ are untouched and fully restorable with a plain cp -al or rsync.

When to use: general files where you want versioned point-in-time backups and need the original folder structure preserved. No extra tool required to restore — every dated folder is browsable with ls and copyable with standard Unix tools. Simpler than Borg/Kopia; no encryption or deduplication across snapshot boundaries.

Compared to rsnapshot: rsync --link-dest keeps your own naming and structure; rsnapshot imposes daily.0/, daily.1/, etc. and manages rotation automatically. --link-dest gives you more control; rsnapshot gives you easier automation.

---

rsnapshot — automated versioned snapshots

What it is: a wrapper around rsync that manages hard-link snapshots automatically using a retention scheme (hourly.0, daily.0, weekly.0, …). Configure sources and retention in /etc/rsnapshot.conf, then run on a schedule.

sudo apt install rsnapshot
# edit /etc/rsnapshot.conf — set snapshot_root, backup sources, retain counts
rsnapshot daily     # run manually or via cron
rsnapshot -t daily  # dry-run / test config

The resulting layout looks like:

/backups/rsnapshot/
  daily.0/  ← most recent
  daily.1/
  daily.2/
  weekly.0/

Each interval directory contains a full view of the source, hard-linked where files are unchanged.

When to use: you want automated versioned backups without writing your own --link-dest rotation script, and you don't mind that the destination uses rsnapshot's own directory naming rather than your original structure. Good for simple setups (home directories, config files) where the rotation automation saves time.

Not ideal for: frequently-changing large files (game saves, databases) — use Kopia or Borg instead for efficient deduplication across many changed blocks.

---

Choosing the right tool

Scenario	Recommended tool
Minecraft worlds, game saves, Steam prefixes — change on every write	Kopia (built-in) or Borg
Media library, ROMs — rarely change, just need a copy	rsync plain
General files — want versioning, want original folder structure	rsync --link-dest
Want automated rotation without scripting --link-dest yourself	rsnapshot
Multi-machine deduplicated repo, YAML-driven config (Borgmatic)	Borg

Layout

setup.sh          dispatcher — wizard, direct install, --list, --dry-run
lib/common.sh     shared helpers: logging, prompts, site config, OS detection
services/         one file per service (self-registering)
extras/           non-Docker assets bundled with the repo (e.g. sync_cc.py)

Managing installed services

Every Docker service installs to its own ~/docker/<name>/ folder:

cd ~/docker/immich
docker compose up -d        # start
docker compose logs -f      # logs
docker compose pull && docker compose up -d   # update
docker compose down         # stop

Installing from a USB thumb drive

No git required. Works for anyone with a browser.

1 — Put the repo on the USB

1. On GitHub: click Code → Download ZIP
2. Open your Downloads folder — right-click the ZIP → Extract Here
3. Drag the ubuntu-post-install-main folder onto the USB drive in the file manager sidebar

To update later: download the ZIP again, extract, drag the new folder to the USB and replace the old one.

2 — Run on the target machine

Plug in the USB. Open the ubuntu-post-install-main folder in the file manager, then either:

• Right-click inside the folder → Open in Terminal, then run:

  sudo bash bootstrap.sh
  

• Double-click bootstrap.sh → click Run in Terminal → it prompts for your sudo password and starts the wizard automatically.

Notes

• Everything the wizard installs goes to ~/docker/ on the target machine's disk — only the setup scripts live on the USB.
• exFAT is the best filesystem for the USB — readable on Windows and macOS for easy ZIP extraction, and works fine on Linux.

Compatibility

Tested on Ubuntu 24.04 LTS and 26.04 LTS. Works on any Ubuntu LTS ≥ 22.04; non-LTS releases also work. The wizard shows the detected OS in the header and warns on unknown versions.