start-os/CONTRIBUTING.md

Contributing to StartOS

This guide is for contributing to the StartOS. If you are interested in packaging a service for StartOS, visit the service packaging guide. If you are interested in promoting, providing technical support, creating tutorials, or helping in other ways, please visit the Start9 website.

Collaboration

• Matrix

For project structure and system architecture, see ARCHITECTURE.md.

Environment Setup

Installing Dependencies (Debian/Ubuntu)

Debian/Ubuntu is the only officially supported build environment. MacOS has limited build capabilities and Windows requires WSL2.

sudo apt update
sudo apt install -y ca-certificates curl gpg build-essential
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg-architecture -q DEB_HOST_ARCH) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian bookworm stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install -y sed grep gawk jq gzip brotli containerd.io docker-ce docker-ce-cli docker-compose-plugin qemu-user-static binfmt-support squashfs-tools git debspawn rsync b3sum
sudo mkdir -p /etc/debspawn/
echo "AllowUnsafePermissions=true" | sudo tee /etc/debspawn/global.toml
sudo usermod -aG docker $USER
sudo su $USER
docker run --privileged --rm tonistiigi/binfmt --install all
docker buildx create --use
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # proceed with default installation
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24
nvm alias default 24 # this prevents your machine from reverting back to another version

Cloning the Repository

git clone --recursive https://github.com/Start9Labs/start-os.git --branch next/major
cd start-os

Development Mode

For faster iteration during development:

. ./devmode.sh

This sets ENVIRONMENT=dev and GIT_BRANCH_AS_HASH=1 to prevent rebuilds on every commit.

Building

All builds can be performed on any operating system that can run Docker.

This project uses GNU Make to build its components.

Requirements

• GNU Make
• Docker or Podman
• NodeJS v20.16.0
• Rust (nightly for formatting)
• sed, grep, awk
• jq
• gzip, brotli

Environment Variables

Variable	Description
PLATFORM	Target platform: x86_64, x86_64-nonfree, aarch64, aarch64-nonfree, riscv64, raspberrypi
ENVIRONMENT	Hyphen-separated feature flags (see below)
PROFILE	Build profile: release (default) or dev
GIT_BRANCH_AS_HASH	Set to 1 to use git branch name as version hash (avoids rebuilds)

ENVIRONMENT flags:

• dev - Enables password SSH before setup, skips frontend compression
• unstable - Enables assertions and debugging with performance penalty
• console - Enables tokio-console for async debugging

Platform notes:

• -nonfree variants include proprietary firmware and drivers
• raspberrypi includes non-free components by necessity
• Platform is remembered between builds if not specified

Make Targets

Building

Target	Description
iso	Create full .iso image (not for raspberrypi)
img	Create full .img image (raspberrypi only)
deb	Build Debian package
all	Build all Rust binaries
uis	Build all web UIs
ui	Build main UI only
ts-bindings	Generate TypeScript bindings from Rust types

Deploying to Device

For devices on the same network:

Target	Description
update-startbox REMOTE=start9@<ip>	Deploy binary + UI only (fastest)
update-deb REMOTE=start9@<ip>	Deploy full Debian package
update REMOTE=start9@<ip>	OTA-style update
reflash REMOTE=start9@<ip>	Reflash as if using live ISO
update-overlay REMOTE=start9@<ip>	Deploy to in-memory overlay (reverts on reboot)

For devices on different networks (uses magic-wormhole):

Target	Description
wormhole	Send startbox binary
wormhole-deb	Send Debian package
wormhole-squashfs	Send squashfs image

Creating a VM

Install virt-manager:

sudo apt update
sudo apt install -y virt-manager
sudo usermod -aG libvirt $USER
sudo su $USER
virt-manager

Follow the screenshot walkthrough in assets/create-vm/ to create a new virtual machine. Key steps:

1. Create a new virtual machine
2. Browse for the ISO — create a storage pool pointing to your results/ directory
3. Select "Generic or unknown OS"
4. Set memory and CPUs
5. Create a disk and name the VM

Build an ISO first:

PLATFORM=$(uname -m) ENVIRONMENT=dev make iso

Other

Target	Description
format	Run code formatting (Rust nightly required)
test	Run all automated tests
test-core	Run Rust tests
test-sdk	Run SDK tests
test-container-runtime	Run container runtime tests
clean	Delete all compiled artifacts

Testing

make test                    # All tests
make test-core               # Rust tests (via ./core/run-tests.sh)
make test-sdk                # SDK tests
make test-container-runtime  # Container runtime tests

# Run specific Rust test
cd core && cargo test <test_name> --features=test

Code Formatting

# Rust (requires nightly)
make format

# TypeScript/HTML/SCSS (web)
cd web && npm run format

Code Style Guidelines

Formatting

Run the formatters before committing. Configuration is handled by rustfmt.toml (Rust) and prettier configs (TypeScript).

Documentation & Comments

Rust:

• Add doc comments (///) to public APIs, structs, and non-obvious functions
• Use // comments sparingly for complex logic that isn't self-evident
• Prefer self-documenting code (clear naming, small functions) over comments

TypeScript:

• Document exported functions and complex types with JSDoc
• Keep comments focused on "why" rather than "what"

General:

• Don't add comments that just restate the code
• Update or remove comments when code changes
• TODOs should include context: // TODO(username): reason

Commit Messages

Use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation only
• style - Formatting, no code change
• refactor - Code change that neither fixes a bug nor adds a feature
• test - Adding or updating tests
• chore - Build process, dependencies, etc.

Examples:

feat(web): add dark mode toggle
fix(core): resolve race condition in service startup
docs: update CONTRIBUTING.md with style guidelines
refactor(sdk): simplify package validation logic