Using Nodofi CloudDB

Overview

Same shape as every other worker in this ecosystem: a worker makes an outbound connection to a relay and registers itself under a plain name; an app's NodoCloudDB client sends it one message per operation and waits for one reply. Data is organized by project (Studio's public project id) and table (a name your app picks, e.g. "notes") — one shared store, not a separate database per app.

Three tiers of access: open reads on public tables, a data key for writes, and a wallet signature for private per-user tables — see below.

Requirements

• Node.js 18 or later.
• Windows, Linux (any systemd-based distribution), or macOS (run from source).
• Its defaults (Nodofi's own public relay, a local sqlite file) work as soon as it's installed — nothing strictly needs editing first, unlike the NVM Service Manager.

Quickstart

Windows

1. Download nodofi-clouddb-win-x64.zip and extract it anywhere you'll keep it.
2. Double-click install-startup.bat — installs dependencies, creates .env from .env.example (its defaults already work), registers it to start automatically, and starts it.
3. Open http://localhost:8801 to see connection status.

Linux

Copytar -xzf nodofi-clouddb-linux-x64.tar.gz
cd nodofi-clouddb-linux-x64
sudo ./install.sh

Then open http://localhost:8801 in a browser on that machine.

macOS (or any OS, from source)

Copygit clone <this repository>
cd nodo-clouddb
npm install
cp .env.example .env
npm start

Pick your own WORKER_NAME in .env if you'll run more than one of these, or want it to be addressable by a name you recognize.

Using it from an app

In a Studio project: right-click it → Database…. That provisions the project directly from your browser and shows you a ready-to-paste snippet with your project's data key already filled in — save the key, it's shown only once.

Copy<script src="/js/nodo-clouddb.js"></script>
<script>
  const db = new NodoCloudDB({ project: PROJECT_UID, key: DATA_KEY, relay: RELAY_URL, worker: 'NodofiCloudDB' });

  const notes = db.table('notes');
  const id = await notes.add({ title: 'Hi' });
  const all = await notes.toArray();
  await notes.update(id, { done: true });
  await notes.delete(id);
</script>

The same client (same class, same methods) is also available with no <script> tag at all as a global inside an NVM Service Manager service — a Node port, since a headless service has no HTML to add a script tag to.

Private tables

A project's data key is a bearer secret — anyone who has it can write to that project's public tables. If your app's own source is publicly visible (most Studio-built apps' client-side code is), embedding the key directly in it is a basic guard against casual/accidental writes, not real access control. For anything sensitive, use a private table instead: it requires a signed request from a specific wallet on every operation, including reads, and automatically walls off each signer's rows from everyone else's.

Copyconst vault = db.table('secrets', { private: true, wallet: { address, privateKey } });
await vault.add({ secret: 'only this wallet can read this back' });

Self-hosting vs. Studio's instance

Studio has an official, always-on CloudDB worker — the default if you never change the relay/worker fields in the Database… dialog. Running your own (this download) gives full control of your own data instead; pointing an app at it is the same dialog, just with your own relay address and WORKER_NAME filled in. The default backend is a single sqlite file (zero setup); point DB_DRIVER=mariadb at a real server instead if you need one (what Studio's own instance uses) — see .env.example's own comments.

Uninstalling

Linux: sudo ./uninstall.sh from the folder you extracted (your .env and data are kept). Windows: double-click uninstall-startup.bat, then delete the extracted folder.