Home Explore Help
Sign In
KrakensLab
/
oasis
Watch 3
Star 0
Fork 0
Files
Tree: 0b9fb75750
Branches Tags
oasis
/
docs
/
devs
/
install.md

install.md 4.8 KB
History Raw

Developer Install

To deploy the development environment:

git clone https://code.03c8.net/KrakensLab/oasis
cd oasis
bash install.sh
cd src/server
npm run dev

Once Oasis is started in dev mode, visit http://localhost:3000.

The backend restarts automatically (via nodemon) whenever you save changes to .js or .json files in src/backend/, src/models/, src/views/, or src/client/. Static assets (src/client/assets/) do not trigger a restart. Page autoreload is not available because we avoid using JavaScript in the browser — reload the page manually to display your changes.

Two-process architecture

Oasis runs as two cooperating Node processes:

  • SSB_server.js — boots the local Secure Scuttlebutt sbot (gossip, EBT, friends, blobs, LAN, search, box, query, tangle, links, backlinks). Owns ~/.ssb.
  • backend.js — Koa HTTP server that connects to the sbot through ssb-client and renders pages with hyperaxe. Serves http://localhost:3000.

The backend talks to the sbot over a local Unix socket. If you only restart the backend (the default in npm run dev), the sbot keeps running. If you change anything under src/server/ or anything that holds an SSB handle inside a model, restart the sbot too (kill the SSB_server.js process and re-run npm start).

npm scripts

Run these from src/server/:

  • npm start — boots the SSB sbot in the background, waits ~10 s, then starts the HTTP backend. Use this for an end-to-end local run.
  • npm run start:ssb — start only the SSB sbot.
  • npm run start:backend — start only the HTTP backend (assumes sbot is already running).
  • npm run dev — backend under nodemon watch (auto-restart on file change). Sbot is not watched.

The launcher script at the repo root (oasis.sh) wraps these and detects whether to start in server, pub, or gui mode.

Tests

Unit and integration tests live under test/ at the repo root, grouped per module in test/mods/. Coverage spans 40+ modules including tribes, feed, banking, parliament, courts, jobs, market, shops, media (audio/video/image/document/torrent), maps, pads, calendars, events, tasks, votes, transfers, reports, projects, opinions, activity, AI, CV, LARP, melody, and more.

Run the full suite from the oasis/ directory:

# All modules, each in a subprocess with safe ~/.ssb isolation
bash test/run.sh

# Same, but skip the confirmation prompt
bash test/run.sh --yes

# All modules in a single Node process (no isolation, faster but mixes state)
node test/run.js

# A single module
node test/run.js mods/tribes
node test/run.js mods/media/audios

# Per-module shortcut (no isolation, fast iteration)
bash test/mods/<module>/run.sh

test/run.sh moves your live ~/.ssb to a timestamped backup (~/.ssb-bak-YYYYMMDD_HHMMSS) before the run and creates a fresh empty ~/.ssb for the tests. Stop any running Oasis instance first — only one process can hold ~/.ssb open at a time. Pass --restore to restore the original ~/.ssb after the run finishes (CI uses this).

What the tests cover, how to add a new module suite, and a record of bugs the test harness has caught are documented in test/README.md. When you change a model, add or update its test under test/mods/<module>/ so the change comes with a regression net.

Useful commands while developing

  • npm install — install / refresh dependencies.
  • npm test — run automated tests (calls into the test/ harness).
  • npm run fix — auto-fix formatting and lint issues (also runs as a pre-commit hook).

Directory map (cheat sheet)

  • src/server/ — SSB sbot entry, ssb-config, secret-stack plugin wiring, vendored packages/ssb-server.
  • src/backend/ — Koa HTTP entry (backend.js), middleware, blob handler, URL renderer, sanitizer.
  • src/models/ — per-module data access. Factory functions that receive cooler (and sometimes tribeCrypto, tribesModel) and return query/publish methods.
  • src/views/ — hyperaxe view functions. Pure HTML builders.
  • src/AI/ — local LLM service (ai_service.mjs on port 4001) and context assembler.
  • src/configs/ — oasis-config.json (module toggles, themes, language) and config-manager.js.
  • src/client/assets/ — CSS, theme files, translations (11 languages), static images.
  • docs/ — user and developer documentation (this folder).
  • test/ — test harness (run.sh, run.js, seed.js, helpers/) and per-module test suites in mods/.
  • scripts/ — build helpers (build-deb.sh, node_modules patcher).

Pre-commit checks

The pre-commit hook runs cspell and prettier. See contributing.md for what to do when a check fails (typos go in .cspell.json; formatting via npm run fix).