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
• Telegram

Project Structure

/
├── assets/
├── container-runtime/
├── core/
├── build/
├── debian/
├── web/
├── image-recipe/
├── patch-db
└── sdk/

assets

screenshots for the StartOS README

container-runtime

A NodeJS program that dynamically loads maintainer scripts and communicates with the OS to manage packages

core

An API, daemon (startd), and CLI (start-cli) that together provide the core functionality of StartOS.

build

Auxiliary files and scripts to include in deployed StartOS images

debian

Maintainer scripts for the StartOS Debian package

web

Web UIs served under various conditions and used to interact with StartOS APIs.

image-recipe

Scripts for building StartOS images

patch-db (submodule)

A diff based data store used to synchronize data between the web interfaces and server.

sdk

A typescript sdk for building start-os packages

Environment Setup

Clone the StartOS repository

git clone https://github.com/Start9Labs/start-os.git --recurse-submodules
cd start-os

Continue to your project of interest for additional instructions:

• core
• web-interfaces
• build
• patch-db

Building

This project uses GNU Make to build its components. To build any specific component, simply run make <TARGET> replacing <TARGET> with the name of the target you'd like to build

Requirements

• GNU Make
• Docker
• NodeJS v20.16.0
• sed
• grep
• awk
• jq
• gzip
• brotli

Environment variables

• PLATFORM: which platform you would like to build for. Must be one of x86_64, x86_64-nonfree, aarch64, aarch64-nonfree, raspberrypi
  • NOTE: nonfree images are for including nonfree firmware packages in the built ISO
• ENVIRONMENT: a hyphen separated set of feature flags to enable
  • dev: enables password ssh (INSECURE!) and does not compress frontends
  • unstable: enables assertions that will cause errors on unexpected inconsistencies that are undesirable in production use either for performance or reliability reasons
  • docker: use docker instead of podman
• GIT_BRANCH_AS_HASH: set to 1 to use the current git branch name as the git hash so that the project does not need to be rebuilt on each commit

Useful Make Targets

• iso: Create a full .iso image
  • Only possible from Debian
  • Not available for PLATFORM=raspberrypi
  • Additional Requirements:
    • debspawn
• img: Create a full .img image
  • Only possible from Debian
  • Only available for PLATFORM=raspberrypi
  • Additional Requirements:
    • debspawn
• format: Run automatic code formatting for the project
  • Additional Requirements:
    • rust
• test: Run automated tests for the project
  • Additional Requirements:
    • rust
• update: Deploy the current working project to a device over ssh as if through an over-the-air update
  • Requires an argument REMOTE which is the ssh address of the device, i.e. start9@192.168.122.2
• reflash: Deploy the current working project to a device over ssh as if using a live iso image to reflash it
  • Requires an argument REMOTE which is the ssh address of the device, i.e. start9@192.168.122.2
• update-overlay: Deploy the current working project to a device over ssh to the in-memory overlay without restarting it
  • WARNING: changes will be reverted after the device is rebooted
  • WARNING: changes to init will not take effect as the device is already initialized
  • Requires an argument REMOTE which is the ssh address of the device, i.e. start9@192.168.122.2
• wormhole: Deploy the startbox to a device using magic-wormhole
  • When the build it complete will emit a command to paste into the shell of the device to upgrade it
  • Additional Requirements:
    • magic-wormhole
• clean: Delete all compiled artifacts