Full Setup Guide

First, let's make sure you have everything. Check off each item as you go:

Once you have everything:

1. Attach the NVMe SSD to the NVMe HAT/Base board — it clicks into the M.2 slot at an angle, then press down and screw it in.
2. Connect the HAT to the Pi 5 — plug in the flat ribbon cable to the PCIe connector on the underside of the Pi.
3. Insert the MicroSD card into the Pi's card slot (we'll flash it in the next step).
4. Don't power it on yet — we need to flash the OS first.

We need to install Raspberry Pi OS on the MicroSD card. This is what powers your Pi.

1. Download and install Raspberry Pi Imager on your computer (Mac, Windows, or Linux).
2. Open the Imager and configure these settings:

3. Before writing, click the gear icon (⚙️) or "Edit Settings" and configure:

4. Click Write and wait for it to finish (~5 min).
5. Put the MicroSD card back into the Pi and plug in the power supply.
6. Wait ~2 minutes for the Pi to boot up for the first time.

SSH (Secure Shell) lets you control the Pi from your computer's terminal. Think of it as a remote control for the command line.

On Mac: Open Terminal (search Spotlight for "Terminal").
On Windows: Open PowerShell (search Start for "PowerShell").

Type this command and press Enter:

$ ssh pi@ughstorage.local

Enter the password you set in Step 2 when prompted. You should see a welcome message and a command prompt like pi@ughstorage:~ $

Your NVMe SSD is a blank drive right now. We need to partition it (tell the system to use the whole drive as one big space) and format it (prepare it to store files). This is like formatting a USB drive — but bigger.

4a. Verify the Pi sees your SSD

$ lsblk

NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
mmcblk0     179:0    0  29.7G  0 disk
├─mmcblk0p1 179:1    0   512M  0 part /boot/firmware
└─mmcblk0p2 179:2    0  29.2G  0 part /
nvme0n1     259:0    0 931.5G  0 disk

You should see nvme0n1 in the list — that's your SSD. The size should match what you bought (e.g., ~931GB for a 1TB drive).

4b. Create a partition

$ sudo fdisk /dev/nvme0n1

This opens an interactive partition tool. Type these keys one at a time, pressing Enter after each:

4c. Format the partition

$ sudo mkfs.ext4 /dev/nvme0n1p1

This formats the partition with the ext4 filesystem — the standard Linux format. It's reliable, fast, and handles large files perfectly. This may take 10–30 seconds depending on drive size.

Mounting means connecting the SSD to a folder so the system can read and write files to it. Think of it like plugging in an external hard drive — except we tell Linux exactly where to "plug it in."

5a. Create the mount point and mount

$ sudo mkdir -p /mnt/nvme
$ sudo mount /dev/nvme0n1p1 /mnt/nvme
$ sudo chown pi:pi /mnt/nvme

Here's what each line does:

• mkdir -p /mnt/nvme — Creates the folder /mnt/nvme where the SSD will be accessible
• mount — Connects the formatted partition to that folder
• chown pi:pi — Gives your user account permission to read/write files on the SSD

5b. Make it permanent (auto-mount on boot)

Without this step, the SSD would disconnect every time the Pi restarts. This command adds it to the system's startup list:

$ echo '/dev/nvme0n1p1 /mnt/nvme ext4 defaults,noatime 0 2' | sudo tee -a /etc/fstab

5c. Verify everything worked

$ df -h /mnt/nvme

Filesystem      Size  Used Avail Use% Mounted on
/dev/nvme0n1p1  916G   28K  870G   1% /mnt/nvme

You should see your drive's full capacity. The "Avail" column is your usable storage space.

Now for the good part — installing the UghStorage server software. This is a single script that handles everything automatically.

$ cd /home/pi
$ git clone https://github.com/hneogy/ughstorage.git
$ cd ughstorage/server
$ chmod +x setup.sh ble_setup_service.sh
$ ./setup.sh

The setup script runs 6 steps automatically. Here's what it's doing behind the scenes:

============================================
  UghStorage Setup (v2 - Multi-Tenant)
============================================

[1/6] Installing system dependencies...
[2/6] Installing cloudflared...
  cloudflared installed: 2025.x.x
[3/6] Creating Python virtual environment...
  Installed Python packages.
[4/6] Creating storage directories...
  /mnt/nvme/storage
  /mnt/nvme/thumbnails
[5/6] Configuring environment...
  Environment saved to /home/pi/ughstorage/server/.env
[6/6] Creating systemd service...
  Service installed: ughstorage

============================================
  Setup complete!
============================================

This script sets up Bluetooth Low Energy (BLE) so the UghStorage iPhone app can find your Pi wirelessly and configure it — no cables or keyboard needed.

$ sudo bash ble_setup_service.sh

Here's what this script configures:

[INFO]  ==========================================
[INFO]   UghStorage BLE Setup Installer
[INFO]  ==========================================
[INFO]  Updating package lists...
[INFO]  Installing Bluetooth and NetworkManager packages...
[INFO]  Installing Python dependencies...
[INFO]  Dependencies installed.
[INFO]  Configuring NetworkManager...
[INFO]  NetworkManager is active.
[INFO]  Configuring Bluetooth...
[INFO]  Bluetooth configured.
[INFO]  Config directory ready at /etc/ughstorage
[INFO]  Creating systemd service: ughstorage-ble...
[INFO]  Service created and started.
[INFO]  ==========================================
[INFO]   Installation complete!
[INFO]  ==========================================

Let's start the server and make sure everything is running properly.

8a. Start the server

$ sudo systemctl start ughstorage

8b. Check the status

$ sudo systemctl status ughstorage

● ughstorage.service - UghStorage personal cloud storage
     Loaded: loaded (/etc/systemd/system/ughstorage.service; enabled)
     Active: active (running) since ...
   Main PID: 1234 (python3)
      Tasks: 3 (limit: 4915)
        CPU: 1.234s
     CGroup: /system.slice/ughstorage.service
             └─1234 /home/pi/ughstorage/server/venv/bin/python3 -m uvicorn main:app ...

Look for "active (running)" — that means the server is up and healthy.

8c. Quick health check

$ curl http://localhost:8000/health

{"status": "ok", "version": "1.0.0", ...}

The hard part is done! Now grab your iPhone and let the app do the rest.

1. Download UghStorage from the App Store Coming Soon
2. Create an account in the app
3. Tap "Add Device" to start the setup wizard

The app will walk you through three automatic steps: