Watch 1

Star 0

HTTPS

Download ZIP Download TAR.GZ Download BUNDLE Open with VS Code Open with VSCodium Open with Intellij IDEA

🌍 Common OS: Federated Cooperative Infrastructure

Welcome to the century-long project to build a fairer, federated world! ✨

Common OS is an open-source platform for communities, cooperatives, and dreamers. We’re building tools for the next 100 years—together. Everyone is welcome, and every contribution matters.

🚀 Quick Start

git clone https://codeberg.org/your-org/common-os.git
cd common-os
./setup

• Read the docs for a full guide and architecture.
• Try the app or node for hands-on hacking.
• Use the /setup page to pick your language and get started fast.

🌐 Language Support

This project welcomes everyone! Docs and setup are available in:

• 🇺🇸 English
• 🇮🇪 Gaeilge
• 🇰🇪 Kiswahili
• 🇳🇬 Hausa
• 🇳🇬 Yorùbá
• 🇪🇹 Amharic

Want to help translate? See docs/contributing/!

🧑‍💻 Cool Git Stuff

• Fork and branch: git checkout -b my-feature
• Keep up to date: git pull origin main
• Sign your commits: git config commit.gpgsign true
• Check commit signatures: ./scripts/verify-commits.sh
• See commit history: git log --oneline --graph --decorate

📚 Learn More

• Read the Docs
• Contributing Guide
• Architecture
• Getting Started

🤝 Join Us

Whether you’re a coder, translator, organizer, or just curious—this project is for you. Let’s build the future, one commit at a time.

---

This is a living, evolving project. Your ideas and energy shape its next century.

1. Install WSL2 and Ubuntu. (Windows, Linux onwards)
2. Open Ubuntu 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

Offline Translation (Privacy-Friendly)

Common OS now supports two local-only translation paths:

1. On-the-fly resource planning translation (served by the node):

• Endpoint: POST /api/translate/resource
• Input: {"text":"Need water and food for 20 homes","target_locale":"sw"}
• Behavior: uses a local glossary in node/data/resource_glossary.json and never calls cloud translators.

2. Static pretranslation for docs/frontend (generated files, not live web translation):

# Frontend catalog pretranslation
python3 scripts/pretranslate_offline.py --mode frontend --lang sw --engine auto
# Docs content pretranslation
python3 scripts/pretranslate_offline.py --mode docs --lang sw --engine auto
# Both
python3 scripts/pretranslate_offline.py --mode both --lang sw --engine auto

Engine modes:

• auto: use local Argos models if installed, otherwise deterministic glossary fallback.
• argos: require local Argos models (fails if missing).
• glossary: always use local glossary replacement only.

No Google Translate, no network translation API, no external runtime dependency.

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.