ddd2787b73
Rama de desarrollo experimental sobre el Oasis de epsylon, sin afiliacion con el proyecto original. Base: 0.9.5. Trae el modulo Karvan —salas efimeras en memoria con autodestruccion por TTL, chat que funciona sin JavaScript y llamadas de audio y video sobre WebRTC— con el enlace en el menu lateral por el mismo patron que el resto de modulos: renderKarvanLink calcado de renderPollsLink, entrada en modules_view y en la lista de /modules. Los estilos del modulo van en su propia hoja, styles/karvan.css, siguiendo el patron de highlight.css: asi se ve igual con cualquier tema, sin depender del tema movil. Sin servidores ICE de terceros: no hay STUN de fabrica, porque un STUN aprende la IP publica y el momento de cada llamada. Solo candidatos host salvo que se configure un TURN propio en oasis-config.json, con credenciales efimeras por el mecanismo REST de coturn. El codigo propio vive separado —views/fork/, backend/fork_routes.js, models/karvan_model.js y translations/fork/— de modo que sobre los ficheros de upstream solo hay enganches de una linea y cada version nueva se integra sin arrastrar nada. Respecto al arbol de Android: fuera el wrapper y main.js, que es su arranque; el tema vuelve a Dark-SNH y se restauran los modulos que en movil se recortan por peso. Verificado arrancando sin OASIS_MOBILE: nueve rutas OK, menu lateral de upstream con 27 grupos y el enlace de Karvan, cero rastro de la interfaz movil (ni hexagonos, ni topbar, ni barra inferior), y una sala creada y servida.
86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
# Developer Install
|
|
|
|
To deploy the development environment:
|
|
|
|
```shell
|
|
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](http://localhost:3000).
|
|
|
|
The backend restarts automatically (via [nodemon](https://nodemon.io)) 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:
|
|
|
|
```sh
|
|
# 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`](../../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`](./contributing.md) for what to do when a check fails (typos go in `.cspell.json`; formatting via `npm run fix`).
|