Pi-Guide

A collection of setup guides for self-hosted services and utilities on a Raspberry Pi, covering networking, home automation, media, and backup tools.

Disclaimer: These guides are provided as-is, with no guarantee against misconfiguration or data loss. Each guide is based on established community references, linked under its own Sources section.

Getting Started

Setting up the Raspberry Pi

1. Download and install the Raspberry Pi Imager from https://www.raspberrypi.com/software/
2. Insert your micro SD card, open Raspberry Pi Imager, and select your Pi model and OS. "Raspberry Pi OS Lite (64-bit)" is recommended for headless setups that won't use a desktop environment.
3. Select your storage device and click "Next". When the popup asks if you want to apply custom settings, enter your WiFi credentials and enable SSH under the "Services" tab.
   • You can set your password and hostname here, or later via How to Change Your Password and Hostname.
4. Once flashing finishes, insert the micro SD into your Pi and power it on.

Connecting to the Raspberry Pi

1. Use an SSH client — PuTTY (https://www.putty.org/) on Windows, or Termius from the app store on Mac.
2. Connect to your Pi by entering its IP address or hostname (default is raspberrypi), then enter the username and password you set during imaging above.
   • Raspberry Pi OS hasn't shipped a default pi/raspberry login since April 2022.

Give the Pi a Static IP

The guides in this repo reference the Pi by its IP address, and services like Pi-hole break if that address changes. Pick one:

• Recommended: set a DHCP reservation in your router's settings (usually under LAN > DHCP Server) binding the Pi's MAC address to a fixed IP. Nothing to configure on the Pi itself.
• Or set a static IP on the Pi. Raspberry Pi OS "Bookworm" and newer use NetworkManager — run sudo nmtui, select "Edit a connection", set IPv4 to Manual, and enter an address outside your router's DHCP range.

How to Change Your Password and Hostname

Change Password

SSH into the Pi and enter the following to change your password:

sudo passwd

Change Hostname

1. SSH into the Pi, and open the hosts file by entering:

   sudo nano /etc/hosts

2. At the bottom, change raspberrypi to whatever name you want for the Pi.
3. To save the file, press Ctrl+X then Y then Enter.
4. Next, open the hostname file by entering:

   sudo nano /etc/hostname

5. Change raspberrypi to whatever name you want for the Pi.
6. To save the file, press Ctrl+X then Y then Enter.
7. Reboot:

   sudo reboot

Starting Over (Factory Reset)

There's no software reset button on a Pi — wiping the SD card and reflashing is the actual fresh start. The good news is that's less work than it sounds:

• Raspberry Pi Imager already formats the card as part of writing the OS — you don't need a separate formatting step. Just power off the Pi, remove the card, and repeat Setting up the Raspberry Pi above from a computer.
• If you only want to wipe the card (no new OS), select "Erase" from Imager's OS list instead of an operating system.
• Imager remembers your last-used WiFi/SSH/username settings (gear icon, or Ctrl+Shift+X), so you're not retyping everything each time.
• If you set up a DHCP reservation per Give the Pi a Static IP, that lives on your router, not the SD card — it survives a reset and the Pi will get the same address again automatically.

Faster, if you do this often: reflashing still means redoing every setup step from scratch — WiFi, SSH, hostname, and all your guides. Skip that by keeping a clean backup instead. Right after your first full setup (before installing anything else), take a backup with raspiBackup. Next time you want to start over, restore that backup onto the card instead of reflashing — it comes back exactly as it was the moment you backed it up, in a fraction of the time.

Upgrading to a New OS Release

When a new Raspberry Pi OS release comes out (e.g., "Bookworm" to "Trixie"), don't upgrade in place with apt full-upgrade or by editing your sources lists. Raspberry Pi doesn't support or recommend upgrading a running system across major versions — it can work, but it fails unpredictably, and on a headless Pi that means repairing a half-finished upgrade over SSH (with your network's DNS down, if it runs Pi-hole).

Instead:

1. Flash the new release onto a new SD card, per Setting up the Raspberry Pi.
2. Restore your services and settings from backup — see Snapshot Backups. (A raspiBackup image restore puts back the old OS, so it doesn't help here.)
3. Keep the old card untouched. If anything goes wrong, swap it back in and you're running again in a minute.

There's no rush: each release keeps getting security updates for a while after the next one comes out.

Table of Contents

Grouped by category. Indented guides depend on their parent guide — each guide's own Prerequisites section lists exactly what it needs.

Core System Setup

• SSH Hardening — key-based login, firewall (including which services it blocks), fail2ban
• Unattended-Upgrades — automatic security updates
• Log2Ram — reduce SD card wear
• System Tuning & Cleanup — free SD card space, swap less, trim unused services, update the bootloader
• Watchdog — auto-reboot on system hang
• UPS — shut down cleanly before a UPS runs flat, and power back on afterwards (NUT)
• Job Monitoring — alerts when a scheduled job fails or stops running
• XRDP — remote desktop access

Containers & Monitoring

• Docker
• Portainer — Docker web UI
• Watchtower — auto-update Docker containers
• Grafana — hardware metrics dashboard
• Uptime Kuma — service status page and alerts
• Homepage — dashboard linking all your services

Networking & DNS

• Pi-hole — network-wide ad blocking
  • Unbound — recursive DNS resolver
  • nebula-sync — sync two Pi-holes
  • keepalived — Pi-hole failover
• PiVPN — WireGuard VPN server
• Tailscale — remote access without port forwarding
• DDNS — a hostname that follows your home IP (DuckDNS)
• NGINX — web server / reverse proxy
  • GoAccess — NGINX log analytics

Home Automation

• Home Assistant
  • Room Assistant — BLE room presence detection
  • Mosquitto — MQTT broker
  • Zigbee2MQTT — Zigbee devices without brand hubs
• diyHue — Philips Hue Bridge emulator
• Hyperion or HyperHDR — ambient TV lighting

Storage & Backup

• NAS — network-attached storage
• immich — self-hosted photo/video backup
  • Immich Backup — encrypted, versioned backups of photos + database with BorgBackup
• Syncthing — sync files between your devices
• raspiBackup — scheduled system backups
• Snapshot Backups — daily file-level snapshots to USB, plus a NAS copy
• Rclone — cloud backup

Media & Gaming

• Jellyfin — media streaming server
  • Sonarr, Radarr & Prowlarr — automated media library management, plus Seerr for requests
    • Gluetun — route qBittorrent through a VPN, with a kill switch
• RetroPie — retro game emulation

Security & Passwords

• Vaultwarden — self-hosted Bitwarden password manager

Apple Ecosystem

• Scrypted — bring any camera into HomeKit

TV

• webOS Dev Mode Renewal — keep an LG TV's Developer Mode from expiring

Personal Finance

• Actual Budget — self-hosted budgeting app
• Wealthsimple to Actual Budget Sync — automated transaction import

Archived

No longer maintained; kept for reference.

• AltServer — sideload apps to iOS without a computer