commit 65a0e268c0f3ebecc22f90b5fe51e644eb417ea0 Author: mmabdalla <101379618+mmabdalla@users.noreply.github.com> Date: Sat Mar 14 06:31:59 2026 +0200 feat: initial commit - founding documents diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bf01041 --- /dev/null +++ b/.gitignore @@ -0,0 +1,32 @@ +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# Build output directories +/build/ +/out/ +/dist/ +*.iso +*.img +*.tar.gz + +# Keys and secrets +*.key +*.pem +*.crt +id_rsa +id_ed25519 +.env +.env.local +.env.*.local + +# Temporary files +*.tmp +*.bak +*.swp +*~ diff --git a/README.md b/README.md new file mode 100644 index 0000000..e3c1691 --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ +# Sawa Server (SS) + +## Overview +Sawa Server (CodeName: SS) is an Alpine Linux-based USB server node project. The primary deliverable is a customized, bootable USB stick that instantly provisions a machine as a Sawa network node. + +**Note: This is NOT a web application.** It is an infrastructure project focused on system-level configuration, network provisioning, and hardware abstraction using the lightweight and secure Alpine Linux environment. + +## Vision +The vision for Sawa Server is to create a zero-touch, highly resilient, disposable infrastructure layer. By booting entirely from a USB drive (and eventually running diskless in RAM), nodes can be deployed instantly, wiped cleanly without leaving traces on the host machine, and replaced seamlessly in the Sawa mesh network. + +MVP Success Criteria: Insert USB into any x86_64 machine, power on, complete ss-init wizard in under 10 minutes, node is online and visible to the Sawa network. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..167aeec --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog + +All notable changes to the Sawa Server (SS) project will be documented in this file. + +## [v0.1.0] - Current State +### Added +- Initial project scaffolding and core founding documents. +- Defined project vision, roadmap phases, and AI guidelines. +- Established Git repository structure and contribution conventions. diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md new file mode 100644 index 0000000..3c8773f --- /dev/null +++ b/docs/CLAUDE.md @@ -0,0 +1,15 @@ +# AI Agent Instructions for Sawa Server (SS) + +You are assisting with the **sawa-server** project. + +## Project Context +- **Name:** sawa-server +- **Codename:** SS +- **Nature of the project:** Alpine Linux USB server node project. This is **NOT** a web app. The end product is a bootable USB stick. + +## Guidelines +1. **System-Level Focus:** Focus on shell scripting, Alpine Linux package management (`apk`), system services (`OpenRC`), minimal disk partitioning, and network configurations. +2. **Minimalism:** Alpine Linux is strictly minimal. Always prefer lightweight native tools (e.g., `busybox`, `ash` instead of `bash`). +3. **No Web Frameworks:** Do not suggest Node.js, React, or any web frameworks unless explicitly requested for a localized control interface. +4. **Resiliency & State:** The system will transition to running diskless in RAM. Data persistence requires specific Alpine tools like Alpine Local Backup (`lbu`). Commands must respect this ephemeral environment. +5. **Project Structure:** *Never* use the project root folder for new files unless absolutely necessary. Place all documentation (except `README.md`) in the `docs/` folder and organize source code into appropriate subdirectories. `README.md` must stay in the project root for git forge display. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..66a203f --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Contributing to Sawa Server + +Thanks for contributing to Sawa Server (SS)! + +## Commit Conventions +We follow the same commit conventions as the `sawa-control-panel` project. Please ensure your commits adhere to these rules: + +- **feat:** A new feature (e.g., `feat: add ss-init script for first boot`) +- **fix:** A bug fix (e.g., `fix: resolve issue with lbu commit on unmounted drive`) +- **docs:** Documentation only changes +- **style:** Changes that do not affect the meaning of the code (formatting, missing spaces, etc.) +- **refactor:** A code change that neither fixes a bug nor adds a feature +- **perf:** A code change that improves performance +- **test:** Adding missing tests or correcting existing tests +- **chore:** Changes to the build process or auxiliary tools and scripts + +Please write your commit messages in the imperative mood (e.g., "Add feature" instead of "Added feature"). + +## General Guidelines +- Keep scripts POSIX-compliant or standard `ash` compatible, given our Alpine Linux environment. +- Test changes on actual bootable media or a compatible VM before submitting. diff --git a/docs/ISSUES.md b/docs/ISSUES.md new file mode 100644 index 0000000..137cf62 --- /dev/null +++ b/docs/ISSUES.md @@ -0,0 +1,9 @@ +# Open Issues + +## Phase 1 & 2 Blockers +- **[ISSUE-1] Base Image Selection:** Determine exactly which Alpine Linux flavor (Standard vs. Extended) provides the best balance of required packages and size for our base image. +- **[ISSUE-2] Core Package List:** Define the minimal set of `apk` packages that must be injected into the base build before Phase 2. +- **[ISSUE-3] `ss-init` Prompt Design:** Outline the exact parameters the first boot wizard needs to ask the user (e.g., hostname, static IP vs DHCP, mesh participation rules). + +## General +- **[ISSUE-4] Hardware Compatibility:** Document any known USB boot issues, UEFI/BIOS quirks, or secure boot obstacles on target hardware architectures. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..eeab424 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,26 @@ +# Sawa Server (SS) Roadmap + +## Phase 1: Base Alpine USB Build +- Prepare base Alpine Linux USB boot medium. +- Establish `sys` mode installation (current state). +- Document current baseline configuration and manual build steps. + +## Phase 2: First Boot Wizard +- Develop the `ss-init` interactive initialization script. +- Automate initial network configuration, key generation, and identity setup. +- Provide a seamless onboarding experience upon first boot. +- ss-init completion time target: under 10 minutes from power-on to node online. + +## Phase 3: Diskless/RAM Mode +- Transition from `sys` mode to a diskless setup running entirely in RAM. +- Implement Alpine Local Backup (`lbu`) for intentional state persistence across reboots. +- Optimize image size and boot speed for rapid node deployment. + +## Phase 4: Node Cloning and Imaging Tools +- Create scripts and tools to rapidly clone the configured USB stick. +- Automate the flashing process for mass deployment of replica nodes. + +## Phase 5: Multi-node Discovery and Mesh +- Implement network discovery protocols for peer-to-peer awareness. +- Configure automatic mesh networking between multiple SS nodes on the same network. +- Establish secure inter-node communication and load distribution.