Welcome! Thank you for your interest in contributing to the growing ecosystem of open software. We call the software applications that run on StartOS “services.” This distinction is made to differentiate from “applications” (apps), which are generally run on a client, and used to access server-side software (services). To run services on StartOS, a package of file components needs to be composed. This guide will dive into the basic structure of how to compose this package.
Check out the glossary to get acquainted with unfamiliar terms. The bottom of this guide also includes support links, including a master checklist.
Almost any type of open source software can be run on StartOS. No matter what programming language, framework, database or interface the service has, it can be adapted for StartOS. This is made possible by the power of Docker containers (don’t worry, we’ll get to this). We do have a few recommendations for choosing a service that will perform optimally across platforms:
It either has a web user interface (it can be interacted with in a web browser), or is server software that external applications or internal services can connect to. Please keep in mind that StartOS users are not expected to have SSH and/or CLI access.
The interfaces supported are: HTTP, TCP, and REST APIs
It can be compiled for ARM (arm64v8 - namely, the Raspberry Pi) and/or x86_64 (amd64 - most desktops, laptops, and servers)
It can be served over TOR
It creates a container image that is optimized for size (under 1GB) to save device space and expedite installation time
Anytime you use a gitclone command in this guide, it will create a new directory with code in it, so make sure you are executing this command from a directory that you want to store code in, such as your home folder.
Docker - Docker is currently the only supported containerization method for StartOS. This declares the necessary environment and building stages for your package to run. Install the desktop GUI or via the command line:
We need to enable cross-arch emulated builds in Docker (unless you are building on an ARM machine, such as an M1 Mac - in which case, skip this step).
dockerrun--privileged--rmlinuxkit/binfmt:v0.8
Buildx - This adds desirable new features to the Docker build experience. It is included by default with Docker Desktop GUI. If Docker was installed via command line, additionally run:
dockerbuildxinstalldockerbuildxcreate--use
Rust & Cargo - Cargo is the package management solution for the Rust programming language. It is needed to build the Start SDK. The following will install both Rust and Cargo:
curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
Verify install:
cargo--version
Start SDK - StartOS has an embedded Software Development Kit (SDK). You can install this component on any system, without needing to run StartOS.
Deno (an optional component for more advanced SDK features) - A simple, modern and secure runtime for JavaScript and TypeScript that uses V8 and is built in Rust. It is used to enable the scripting API portion of the SDK.
A Dockerfile defines the recipe for building the environment to run a service. Currently, StartOS only supports one Dockerfile per project (i.e. no Docker compose), so it should include any necessary database configurations. There are several methods to build a Dockerfile for your service.
First, check to see if the upstream project has already built one. This is usually your best source for finding Docker images that are compatible with ARM. Next, you can:
Make a new Dockerfile, and pull in an image the upstream project hosted on Docker Hub as the base
Make a new Dockerfile, and pull in a small distribution base (eg. alpine) and compile the build environment yourself using the upstream project source code
After coding the build steps, build the Docker image using dockerbuildx, replacing the placeholder variables:
The resulting docker-images/aarch64.tar or docker-images/x86_64.tar artifact (depending on if you used --platform=linux/arm64 or --platform=linux/amd64 is the Docker image that needs to be included in the s9pk package.
Once we have a Docker image, we can create the service wrapper. A service wrapper is a repository of a new git committed project that “wraps” an existing project (i.e. the upstream project). It contains the set of metadata files needed to build a s9pk, define information displayed in the user interface, and establish the data structure of your package. This repository can exist on any hosted git server - it does not need to be a part of the Start9 GitHub ecosystem.
The following files should be included in the service wrapper repository:
manifest.yaml, which defines:
The package id - a unique lowercase and hyphenated package identifier (eg. hello-world)
Essential initialization details, such as version
Where you are persisting your data on the filesystem (i.e. mounts and volumes)
Building the final s9pk artifact depends on the existence of the files listed above, and the execution of the following steps (which should be added to the Makefile):
Package the s9pk:
embassy-sdkpack
Verify the s9pk (replace PKG_ID with your package identifier):
embassy-sdkverifys9pkPKG_ID.s9pk
The verification step will provide details about missing files, or fields in the service manifest file.
The s9pk file can be uploaded for distribution to any website, repository, or marketplace. You can also submit your package for publication to the Community Registry by following the submission process.
Start9 has developed a highly extensible scripting API for developers to create the best possible user experience. This is your toolkit for creating the most powerful service possible by enabling features such as:
Configuration
Version migration
Dependencies
Health checks
Properties
Use is optional. To experiment, simply use the existing skeleton from the Hello World wrapper example, changing only the package version in the migration file.
service - open software applications that run on StartOS
package - the composed set of a Docker image, a service manifest, and service instructions, icon, and license, that are formatted into a file with the s9pk extension using embassy-sdk
wrapper - the project repository that “wraps” the upstream project, and includes additionally necessary files for building and packaging a service for eOS
scripts - a set of developer APIs that enable advanced configuration options for services
embassy-sdk - the Software Development Toolkit used to package and verify services for StartOS
open source software - computer software that is released under a license in which the copyright holder grants users the rights to use, study, change, and distribute the software and its source code to anyone and for any purpose
upstream project - the original, source project code that is used as the base for a service
StartOS - a browser-based, graphical operating system for a personal server
eOS - shorthand for StartOS
s9pk - the file extension for the packaged service artifact needed to install and run a service on StartOS