🍓 Raspberry Pi 5
Home Server
^{_{Powered by Ansible}}

Features • Requirements • Getting Started • Port Forwarding • Environment Variables • Security • License

This Ansible configuration automates the setup of a Raspberry Pi Home Server running Raspberry Pi OS. It deploys essential services, enhances security, and ensures consistency across the server environment.

If you find this repository useful, please ⭐️ or fork it!

🚀 Features

Warning

This setup requires your domain to be fully managed by Cloudflare DNS.

Automated Docker installation
Vaultwarden deployment for secure password management
Cloudflare DDNS updater for dynamic IP management
PiVPN (WireGuard) configuration for secure remote access
NextCloud for file synchronization and sharing
Immich for media synchronization with fast-upload speeds

⚙️ Requirements

Raspberry Pi OS Lite (64-bit): Ensure your Raspberry Pi is running the latest version.
Ansible: Install Ansible on your local machine.
Cloudflare-managed domain: Required for dynamic DNS updates and subdomain routing.
Ethernet connection: Use a wired connection for your Raspberry Pi to ensure stable performance.

Important

When flashing your SD card, enable SSH and select the Use password authentication option.

Note

If you choose a custom hostname or user, remember to update the inventory.ini file accordingly.

Static IPv4 configuration: Your Raspberry Pi should have a static IP on your local network. To set the IP to 192.168.2.210, use:
```
sudo nmcli con mod "Wired connection 1" ipv4.addresses "192.168.2.210/24" \
  ipv4.gateway "192.168.2.1" \
  ipv4.dns "192.168.2.1" \
  ipv4.method manual && \
sudo nmcli con up "Wired connection 1"
```
This is a one-time setup. The Ansible playbook will manage IP persistence afterward.

Note

Ensure Avahi is installed and running for .local domain resolution. Alternatively, access the Pi using its IP address directly.

🏁 Getting Started

Clone the repository:

git clone https://github.com/Nitestack/raspberry-pi-5.git ~/raspberry-pi-5

Install required Ansible Galaxy collections:

ansible-galaxy install -r requirements.yml --force # to ensure the latest versions

Run the playbook:

ansible-playbook -i inventory.ini playbook.yml

Important

This only works if you have set up password-less authentication on your Raspberry Pi. Please look at the Security section for more details.

🔌 Port Forwarding

To ensure remote access and proper functionality of the services, configure the following port forwarding rules on your router:

# PiVPN (WireGuard)
# PIVPN_PORT is an environment variable configurable in `secrets.yml`. The default value is `51820`.
public:${PIVPN_PORT}/tcp -> local:${PIVPN_PORT}/tcp

# Caddy (handling NextCloud, Vaultwarden and Immich)
public:443/tcp -> local:443/tcp
public:443/udp -> local:443/udp

🛠️ Environment Variables

To securely configure sensitive data, create a secrets.yml file in the root directory. Copy the secrets.example.yml file and populate the fields as required.

Cloudflare DDNS Updater

Ensure that an A record for your domain is set up, initially pointing to a placeholder IP (e.g., 8.8.8.8). The DDNS script will update it with your public IP. Define the record name in secrets.yml under CLOUDFLARE_RECORD_NAME.

PiVPN Configuration

Add a CNAME record for your PiVPN subdomain, pointing it to the value in CLOUDFLARE_RECORD_NAME. Update the PIVPN_DOMAIN variable in secrets.yml with the correct domain.

Vaultwarden Settings

Create a CNAME record for your Vaultwarden subdomain, directing it to the value specified in CLOUDFLARE_RECORD_NAME. Set the VAULTWARDEN_URL variable in secrets.yml to your Vaultwarden URL.

NextCloud Settings

Create a CNAME record for your NextCloud subdomain, directing it to the value specified in CLOUDFLARE_RECORD_NAME. Set the NEXTCLOUD_URL variable in secrets.yml to your NextCloud URL.

Immich Settings

Create a CNAME record for your Immich subdomain, directing it to the value specified in CLOUDFLARE_RECORD_NAME. Set the IMMICH_URL variable in secrets.yml to your Immich URL. In addition to that, please set your timezone id (TZ identifier) with TIMEZONE (check this Wikipedia article). You also have to set a database password with IMMICH_DB_WORD (only use the characters A-Za-z0-9, without special characters or spaces).

🛡️ Security

1. Add Your Host to Authorized Keys on the Raspberry Pi

To enable secure SSH access, copy your public key to the Raspberry Pi:

ssh-copy-id nhan@raspberrypi.local

2. Update SSH Configuration

Edit the /etc/ssh/sshd_config file on the Raspberry Pi to strengthen security. Update the following settings:

PasswordAuthentication no
UsePAM no

3. Reload the SSH Service

Apply the changes by reloading the SSH service:

sudo systemctl reload ssh

📝 License

This project is licensed under the Apache-2.0 license.

Nitestack/raspberry-pi-5

🍓 Raspberry Pi 5 Home Server Powered by Ansible