Table of Contents

1. Flash Raspberry Pi OS
2. Customize Fields
3. Install
   • Backups
4. Next Steps
5. Troubleshooting

Flash Raspberry Pi OS

First, purchase the following:

• a Raspberry Pi 4
• an SD card (8+ Gb but 16+ is preferable)
• optionally at least one hard drive or USB key to store all that data

Note: The extra storage is strongly encouraged because SD cards are not designed to be constantly written to and degrade quickly.

Flash the SD card with Raspberry PI OS Lite

The Lite version is recommended because we will not need a user interface, screen, a web browsers, etc.

Customize Fields

The services can optionally be customized by editing the yaml files in ./deployments.

Note: If you change any of the usernames or passwords in the yaml files you will need to completely reset.sh because both the database and nextcloud server read the environment variables only when their data directories are empty.

Install

The installation is mostly automated using the install.sh script. So far it has been tested on Ubuntu but Pull Requests are welcome!

In general the steps are:

1. Configure SD card (optionally inject WiFi and ssh keys)
2. ssh into machine and install OS dependencies
3. Install packages that reduce the churn on the SD card
4. Install local helpers (k3sup)
5. Install k3s
6. Verify k3s is up
7. Mount storage drive (so SD card lasts longer)
8. Deploy apps to k3s
9. Start proxy tunnel for Cluster dashboard
10. Perform backup
11. Uninstall apps

Once the apps are deployed, visit https://cloud (or https://cloud.local or https://cloud.lan). Sign in with username admin and password password unless you changed it earlier.

Backups

You can SCP the backup.sh file to the server and run it to perform a backup.

It backs up the following:

• the Postgres database for nextcloud
• all volumes in the cluster
• the k8s configuration (including secrets and keys)

Backing up the SD card

To optionally back up the SD card perform the following:

1. turn off the pi
2. remove the SD card and insert it into a laptop
3. use the "Disk Utility" to resize the main partition down to around 4Gb. If you skip this then the image will be however large your SD card is
4. run sudo dd status=progress if=/dev/sdX | gzip > cloud-backup.img.gz where sdX is your SD card. Sometimes it is /dev/mmcblk0
5. run sudo dd status=progress if=/dev/sdX bs=1M count=5120 | gzip > cloud-backup.img.gz to limit the image size to 5GB (assuming you shrunk it in the Disk Utility) https://stackoverflow.com/a/26909977
6. resize the partition back to the full size using the "Disk Utility"

Next Steps

Install the following Nextcloud Apps by clicking your login on the top-right and then clicking "Apps":

• Calendar
• Notes
• Tasks
• Passman

Then, on your Android phone, install the following:

• NextCloud
• DAVx5 and configuration instructions
• Etar Calendar
• Tasks
• Notes
• Set your seedvault backup to use nextcloud too!
• Passman. Instructions because passman needs a root CA and some type of domain (e.g. .lan):
  • Ensure cloud.lan resolves by your router
  • Copy the tls-root-ca.crt to your Android phone's "Download" directory
  • On android, visit Settings -> Security -> Encryption & Credentials -> Install a certificate -> CA certificate
  • select the tls-root-ca.crt file
  • In Passman, use the URL cloud.lan/nextcloud
  • To debug:
    • To verify the root CA works, try visiting https://cloud.lan in Chromium. You should not need to accept a certificate
    • use adb logcat to view client logs and tail -f ./data/nextcloud.log by clicking Exec on a nextcloud-server instance in the Kuberneted Dashboard (run the proxy command in the CLI to start it up)
    • To use a different TLD other than .lan, search-and-replace .lan in this repo

Even more!

• git hosting server gitea
• AWS S3-compatible object store min.io: arkade install minio

Install OpenMediaVault for NFS mounts

(steps)

curl -SLfs https://github.com/OpenMediaVault-Plugin-Developers/installScript/raw/master/install | sudo bash -x
# Set the port to something other than 80: https://openmediavault.readthedocs.io/en/5.x/various/advset.html
omv-firstaid
sudo reboot # important for the nfs service to start up

Connect from another location

Your phone can connect to https://cloud from another location if you have one other machine:

1. Enable ssh access to your home network. This usually involves setting up your router to talk to a DDNS provider and then enabling port forwarding on your router to a bastion machine inside your network.
2. Forward the port to a local machine: sudo ssh -i ~/.ssh/id_rsa -L 0.0.0.0:cloud:443 username@myhomeaddress.com The 0.0.0.0 ensures other devices can see the local port and the sudo allows you to listen to ports below 1024
3. Set the hostname of your laptop to be cloud

Troubleshooting

Cannot find cloud

There are 4 causes for not finding the cloud:

1. the pi is not powered on. Check for a light
2. the Operating System is not properly flashed onto the SD card. Plug it into a computer and run the install script.
3. The WiFi information is incorrect. Re-run the script or use an ethernet cable to plug the pi directly into the router

Some modern routers do not support local DNS so you may need to associate the name cloud with the IP address your router gives the machine. Here's how it's done with some common routers:

• ASUS

https://www.scivision.dev/raspberry-pi-wifi-avahi/

Use this command to find all the machines on the network (might need to run a couple of times because of timeouts) nmap -sn 192.168.1.0/24 | grep cloud

This is not super useful but shows all the zeroconf computers on your network:

avahi-browse --all --terminate --resolve

Error messages

• error: yaml: line 30: mapping values are not allowed in this context : Set KUBECONFIG= to the absolute path to the kubeconfig files (generated during the k3sup install ... step)
• If you see "Service Unavailable" then kubernetes may still be downloading images. Check the dashboard to see the status
• If you see "Bad Gateway" nextcloud may still be starting up (it took 3 minutes for me).
  • See the logs in the dashboard by clicking the nextcloud-server-a1b2c3 Pod (not Deployment) and then clicking the Logs button
  • The logs will end with AH00163: Apache/2.4.38 (Debian) PHP/7.4.16 configured -- resuming normal operations when it is complete
• If you get a browser error then try running ping cloud.local. If there is no answer then use the pis hostname and update the nextcloud-ingress.yaml and nextcloud-server.yaml files.

If it does not load up you can view the logs by visiting the k8s dashboard,

File redundancy

See https://old.reddit.com/r/selfhosted/comments/n4pkwk/finally_added_prometheus_and_grafana_on_my_humble/gwxb3se/

32-bit vs 64bit

photoprism no longer builds 32-bit and 64-bit images under the same name. That means that 64-bit images can be referenced by immutable tags while the 32bit image needs to use the armv7 tag

photoprism/photoprism:20211203  # This is the last version that works with 32bit and 64bit raspberry pi

Debugging Nextcloud 500 errors

Run php occ log:watch as the www-data user. Open a shell to nextcloud-server instance and run:

su www-data -s /bin/bash
cs /var/www/html/
php occ log:watch    # <-- shows stack traces