# 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](https://docs.start9.com/latest/developer-docs/). If you are interested in promoting, providing technical support, creating tutorials, or helping in other ways, please visit the [Start9 website](https://start9.com/contribute).


## Collaboration

- [Matrix](https://matrix.to/#/#community-dev:matrix.start9labs.com)
- [Telegram](https://t.me/start9_labs/47471)

## Project Structure

```bash
/
├── assets/
├── core/
├── build/
├── debian/
├── web/
├── image-recipe/
├── patch-db
└── system-images/
```
#### assets
screenshots for the StartOS README

#### core
An API, daemon (startd), CLI (start-cli), and SDK (start-sdk) 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.

#### system-images
Docker images that assist with creating backups.

## Environment Setup

#### Clone the StartOS repository
```sh
git clone https://github.com/Start9Labs/start-os.git
cd start-os
```

#### Load the PatchDB submodule
```sh
git submodule update --init --recursive
```

#### Continue to your project of interest for additional instructions:
- [`core`](core/README.md)
- [`web-interfaces`](web-interfaces/README.md)
- [`build`](build/README.md)
- [`patch-db`](https://github.com/Start9Labs/patch-db)

## Building
This project uses [GNU Make](https://www.gnu.org/software/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](https://www.gnu.org/software/make/)
- [Docker](https://docs.docker.com/get-docker/)
- [NodeJS v18.15.0](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
- [sed](https://www.gnu.org/software/sed/)
- [grep](https://www.gnu.org/software/grep/)
- [awk](https://www.gnu.org/software/gawk/)
- [jq](https://jqlang.github.io/jq/)
- [gzip](https://www.gnu.org/software/gzip/)
- [brotli](https://github.com/google/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](https://github.com/lkhq/debspawn)
- `img`: Create a full `.img` image
    - Only possible from Debian
    - Only available for `PLATFORM=raspberrypi`
    - Additional Requirements:
        - [debspawn](https://github.com/lkhq/debspawn)
- `format`: Run automatic code formatting for the project
    - Additional Requirements:
        - [rust](https://rustup.rs/)
- `test`: Run automated tests for the project
    - Additional Requirements:
        - [rust](https://rustup.rs/)
- `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](https://github.com/magic-wormhole/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](https://github.com/magic-wormhole/magic-wormhole)
- `clean`: Delete all compiled artifacts