Common OS

Common OS is a local-first community platform with:

1. a Rust node backend (identity, discovery, sync, governance)
2. a Preact PWA frontend
3. a Hugo docs site

The vibe: cooperative tech that still works when the internet does not.

Project Layout

• node/ - Rust backend and integration tests
• app/ - Preact frontend (managed with pnpm)
• docs/ - Hugo documentation content and theme
• scripts/ - local build and CI helper scripts
• android/ and fdroid/ - Android and F-Droid packaging work

One-Command Terminal Checklist

Use the interactive launcher for the most common tasks:

./scripts/commonos-terminal.sh

It provides a single menu for app build, CI checks, docs preview, APK build, and server bootstrap.

Quick Start

Linux and macOS

1. Install tools: rustup, cargo, pnpm, hugo, git.

sudo apt update && sudo apt upgrade
sudo apt install rustup cargo pnpm hugo git

2. Clone and open the repository:

git clone ssh://git@codeberg.org/der_autodidact/CommonOS.git
cd CommonOS

3. Build frontend once:

cd app
pnpm install
pnpm run build

4. Run the node backend:

cd ../node
cargo run -- init
cargo run -- serve --port 9876

5. In another terminal, inspect identity:

cd node
cargo run -- show

The local identity key is written to node/data/identity.key with restricted permissions on Unix.

Fast path for repeated development tasks:

./scripts/commonos-terminal.sh

Windows Easiest Path

The easiest Windows setup is WSL2 + Ubuntu, then follow the Linux steps above inside WSL.

1. Install WSL2 and Ubuntu.
2. Open Ubuntu terminal and install dependencies:

sudo apt update
sudo apt install rustup cargo pnpm hugo git openjdk-17-jdk-headless

3. Clone and enter the project:

git clone ssh://git@codeberg.org/der_autodidact/CommonOS.git
cd CommonOS

4. Run the interactive checklist:

./scripts/commonos-terminal.sh

That avoids most of the path, shell, and toolchain friction you get with a fully native Windows setup.

Running the Docs Site

For a local docs preview with live reload:

./scripts/run_hugo_docs.sh

Then open the local URL Hugo prints, usually http://localhost:1313.

For a production-style docs build:

hugo --source docs --destination public

Docs Hosting Recommendation

For now, host docs on static Pages (Codeberg Pages, GitHub Pages, or GitLab Pages) and keep the node service on your own server.

• Docs on Pages: cheapest, fastest, globally cached static hosting.
• Node on your server: best control over trust, identity, and local-first behavior.

This split is usually the best balance of reliability and resource efficiency.

Running the Frontend and Node Together

The simplest end-to-end local flow is:

1. Build the PWA into node/static:

./scripts/build-app.sh

2. Start the node:

cd node
cargo run -- init
cargo run -- serve --port 9876

3. Open the local UI served by the node:

http://127.0.0.1:9876

Example Resource Flows

Local node + UI

./scripts/build-app.sh
cd node
cargo run -- serve --port 9876

• UI: http://127.0.0.1:9876
• Identity API: http://127.0.0.1:9876/api/identity
• Peer list API: http://127.0.0.1:9876/api/peers

Bootstrap seed flow

1. Add bootstrap peers in the UI as host:port or host:port#peerId.
2. Save config.
3. Probe seeds.
4. Inspect status:

curl -sS http://127.0.0.1:9876/api/network/probe/status

Release update flow

Announce an update hash on one node:

curl -sS -X POST http://127.0.0.1:9876/api/network/updates/announce \
	-H 'content-type: application/json' \
	-d '{"release_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","manifest_url":"https://example.org/releases/common-os-v0.2.json","announced_by_peer_id":"demo-peer"}'

Inspect the latest known update:

curl -sS http://127.0.0.1:9876/api/network/updates/latest

Fetch one specific update by hash:

curl -sS http://127.0.0.1:9876/api/network/updates/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Food exchange flow (oats, jam, produce)

1. Open Home and go to the Food section.
2. Choose Give or Find.
3. Add item name and quantity range (for example, oats and 1-3 kg, or jam and 2-6 jars).
4. Add pickup windows (for example, Mon 17:00-19:00 recurring).
5. Optional: publish contact phone/email/Matrix.
6. Post listing.

Notes:

• Only trusted peers (QR-verified) can publish listings.
• Anyone can view public contact details if the poster includes them.
• Perishability is represented by estimated hours remaining.

Testing Guide

Rust unit + integration tests

cd node
cargo test

For a deterministic two-node networking check (discovery + handshake/sync):

./scripts/test-two-node.sh

Includes network-style integration tests in node/tests/integration_test.rs:

• identity generation and display checks
• two-node discovery over mDNS
• two-node noticeboard sync flow
• invalid signature rejection
• governance config roundtrip

Strict quality gate (same checks as CI)

cd ..
./scripts/ci-check.sh

This runs:

• Rust formatting check
• clippy with warnings denied
• full Rust test suite
• frontend formatting check
• frontend build
• docs build with warnings as failures
• commit signature verification for your branch range

Deployment Validation Workflow

If you want confidence before deploying:

1. Run ./scripts/ci-check.sh.
2. Build release backend binaries if needed:

./scripts/build-all.sh

3. Smoke-test a local node:

cd node
cargo run --release -- serve --port 9876

Linux Server Deployment

Recommended guide:

• docs/content/deployment/linux-server.md

Fast path on a verified Linux server clone:

sudo ./scripts/bootstrap-server.sh

This installs the service unit, builds the app and backend, and starts commonos-node under systemd.

Phase 2 Networking (Bootstrap Seeds)

The node now supports a seed list for early wide-area discovery experiments.

1. Connect your app to a running node.
2. On Home, add seed peers as host:port (one per line). Optional: pin a trusted peer identity with host:port#peerId.
3. Save and run Probe Seeds to import reachable peers into local storage.

The seed list is persisted at node/data/network-config.json.

When node serve is running, it also performs periodic seed probing in the background (every 90 seconds) and exposes the latest summary at GET /api/network/probe/status.

This supports both convenience and resilience:

• Domain-based seeds (easy onboarding)
• Direct IP seeds (domain outage fallback)
• Optional peer-id pinning to prevent DNS/IP redirection attacks

Container Image (Podman or Docker)

Podman and Docker use the same Dockerfile, so pick whichever is already installed.

Build image

Podman:

podman build -t common-os:latest .

Docker:

docker build -t common-os:latest .

Run image

Podman:

podman run --rm -p 9876:9876 -v $(pwd)/node-data:/app/node/data common-os:latest

Docker:

docker run --rm -p 9876:9876 -v $(pwd)/node-data:/app/node/data common-os:latest

Android + F-Droid Path

Common OS now includes Android wrapper scaffolding under android/ designed for a foreground-service node model.

• Android wrapper docs: android/README.md
• Packaging script for Android binary + static assets: scripts/android/package-node-assets.sh
• F-Droid preflight script: scripts/android/fdroid-preflight.sh
• F-Droid notes: fdroid/README.md
• Detailed deployment guide: docs/content/deployment/android-fdroid.md

Runtime env variables supported by the node (important for Android app-private storage):

• COMMON_OS_DATA_DIR
• COMMON_OS_STATIC_DIR
• COMMON_OS_BIND_IP

Android environment setup is validated by:

./scripts/android/setup-android-env.sh

This auto-detects the newest installed NDK under ~/Android/Sdk/ndk/<version> and exports NDK_TOOLCHAIN_ROOT for the current shell process.

To build a test APK locally:

./scripts/android/build-apk.sh

Output APK:

android/app/build/outputs/apk/debug/app-debug.apk

Transfer and install on Android (USB example):

adb install -r android/app/build/outputs/apk/debug/app-debug.apk

If you prefer manual transfer:

1. Copy the APK to your phone with USB file transfer, Syncthing, or local share.
2. Open the APK on the phone and allow install from this source.
3. Install and launch Common OS.

If build fails, common missing prerequisites are:

• Rust target: rustup target add aarch64-linux-android
• Android NDK installed from Android Studio SDK Manager (SDK Tools > NDK (Side by side))
• Gradle (android/gradlew or system gradle)
• Java 17+ runtime (sudo apt install openjdk-17-jdk-headless)

Verify Commit Signatures

Default mode verifies only your current branch delta against upstream:

./scripts/verify-commits.sh

Optional modes:

./scripts/verify-commits.sh --all
./scripts/verify-commits.sh --range origin/main..HEAD

Localization

Frontend locale support currently includes:

• English (en-US)
• Spanish (es)
• French (fr)
• Chinese Simplified (zh-CN)
• Arabic (ar)
• Russian (ru)
• Swahili (sw)
• Irish (ga)
• Hausa (ha)

Top-30 spoken language rollout status (app + docs):

• docs/content/architecture/language-coverage-roadmap.md

Account recovery and QR-based add-device roadmap:

• docs/content/architecture/account-recovery-device-linking.md

You can add more locales by creating a new catalog in app/src/i18n/ and registering it in app/src/i18n.ts.

Privacy and GDPR Baseline

Common OS follows a privacy-first baseline (local-first data, no analytics SDKs, minimal data storage), but full legal GDPR compliance requires operator policy and legal review.

• Baseline guide: docs/content/deployment/gdpr-privacy.md

Use that guide as the current compliance checklist for deployment hardening.

Implemented privacy defaults include:

• no-store API cache headers to reduce accidental sensitive data caching.
• Food contact field minimization: if contact is disabled, contact fields are dropped.
• Trusted-posting enforcement for food listings.

Next steps to maximize chance of going viral quickly

1. Ship a sharp 1-minute wow onboarding.
2. One QR scan, instant local mesh post visible across two devices.
3. Record a 30–45 second demo clip.
4. Productize trust story in UX.
5. Make trust states obvious: discovered, verified, trusted.
6. Add one-tap verify in person QR handshake flow.
7. Focus distribution channels with audience fit.
8. F-Droid release plus a clear privacy/offline narrative.
9. Post demo and architecture thread in privacy, self-hosting, and local-first communities.
10. Add social proof loops.
11. Public roadmap with weekly shipped milestones.
12. Changelog with crisp user-facing wins.
13. Invite power users into small beta cohort with feedback board.
14. Instrument activation metrics now.
15. Track first-run success, first peer discovered, first synced noticeboard entry, first trusted peer.
16. Optimize those funnels before spending effort on broader promotion.
17. Prepare trust-first launch page.
18. Use No cloud required and cryptographic trust + local ownership as headline promises.
19. Include threat model and key management explanation in plain language.

Messaging and Trust Roadmap

Roadmap document for food responses, DM-like notification strategy, trust graph progression, and decentralization staging:

• docs/content/architecture/food-messaging-roadmap.md

Noticeboard Tiering Roadmap

Planned tiering for listings and translated feeds:

1. Global
2. National
3. Local

See docs/content/architecture/language-coverage-roadmap.md for details.

Git Remote + Push

Remote is configured as:

git remote add origin ssh://git@codeberg.org/der_autodidact/CommonOS.git

Push main branch:

git push -u origin main

License

GNU Affero General Public License v3.0. See LICENSE.