mirror of
https://github.com/Start9Labs/start-os.git
synced 2026-03-26 02:11:53 +00:00
05dd760388
* fix docs paths * docsLink directive * fix: bugs (#2909) --------- Co-authored-by: Alex Inkin <alexander@inkin.ru>
134 lines
5.2 KiB
Markdown
134 lines
5.2 KiB
Markdown
# 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/packaging-guide/). 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/
|
|
├── 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
|
|
|
|
```sh
|
|
git clone https://github.com/Start9Labs/start-os.git --recurse-submodules
|
|
cd start-os
|
|
```
|
|
|
|
#### 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 v20.16.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
|