Skip to content

📦 Installation

The product runs across two machines: your workstation (macOS) does the heavy lifting — digesting exports, holding the one database — and a small always-on home server (a Raspberry Pi or similar, reachable over SSH) serves the result over your own VPN. Set up both.

1. Workstation (Mac)

mkdir -p ~/.local/bin && curl -fsSL https://raw.githubusercontent.com/NoCloudLife/nocloud-core/main/bin/nocloud \
  -o ~/.local/bin/nocloud && chmod +x ~/.local/bin/nocloud && ~/.local/bin/nocloud init

(make sure ~/.local/bin is on your PATH.) nocloud init clones the code into ~/nocloudme, creates the Python environment and initializes the local database. A Homebrew formula also ships in the repo (Formula/nocloud.rb); it installs from this git repo directly (no tagged release exists yet).

Then:

  1. Configure: nocloud setup — a guided, ASCII-art assistant that detects your network (your Mac's IP, router, and Raspberry Pi candidates on the LAN) and writes ~/nocloudme/config/site.env for you. You can also edit that file by hand (server SSH host/user, service URLs, API keys) — it never travels to git either way.
  2. Check: nocloud doctor — over a dozen checks covering git, Python, the job registry, configuration schema, the database, seeded sections, module manifests, the backup contract, the audit event stream and the upgrade lifecycle.
  3. Bring in your data: nocloud onboard <folder-or-export> — point it at a folder of photos/videos or a WhatsApp export and it copies them in (reversibly — originals are never moved or edited) and builds your first populated view automatically. Anything it doesn't recognize yet (Google Takeout, bank/tax statements, other connectors) it says so plainly rather than guessing; install the matching connector from the Store for those instead.

2. Home server (Pi)

This side is a one-time, mostly-manual setup, run on the Pi itself. The one-time image/package pulls during setup are normal for any self-hosted box; what NoCloudMe itself avoids afterward is the appliance pulling its own code from GitHub on an ongoing basis — the Mac pushes to the Pi over your LAN/SSH instead (see Network & outbound traffic).

  1. Copy the repo over once (from the Mac): rsync -a ~/nocloudme/ pi@<host>:~/nocloudme-repo/.
  2. Run scripts/bootstrap_pi.sh on the Pi (needs docker already installed). It creates the ~/intranet/ directory layout, a Python environment, systemd units for the three native services (settings API, permissions API, ingest service), installs Immich and Home Assistant if they aren't already there — both are real dependencies (the photo pipeline and the home dashboard, not optional extras) — and starts a starter nginx container for the portal. Authelia, Roundcube and Syncthing are opt-in; install them yourself when you want them.
  3. Wire up single sign-on once Authelia is running: the OIDC_SSO runbook (docs/OIDC_SSO.md in the repo — an implementer runbook, outside this manual's own build).
  4. Run scripts/setup_pi.sh for the read-only security sudoers grant the doctor console needs, plus the cron job that keeps the egress allowlist fresh.
  5. WireGuard and the egress lockdown: Network & outbound traffic, Security & privacy.

3. Publish

Back on the Mac: nocloud deploy — builds every page and the API and pushes them to the server.

Command What it does
nocloud onboard <path> bring in a folder of photos/videos or a WhatsApp export, then build
nocloud build build without deploying (into build/site)
nocloud test smoke test against synthetic data
nocloud update pull the latest version and its dependencies
nocloud doctor installation diagnostics (text or JSON)
nocloud jobs job registry: list/status/run <id>
nocloud upgrade full lifecycle: preflight → backup → migrate → build → deploy → verify
nocloud module module SDK: list, doctor, install/remove, registry

Tip

nocloud init installs the code and data, separate from the launcher script itself. Removing ~/nocloudme never touches anything already deployed on the Pi.