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.
Let's get started!
Steps:
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:
arm64v8
) and/or (amd64
)A basic development and testing environment includes:
These tools may or may not be necessary, depending on your environment and the package you are building.
sudo apt-get install -y build-essential openssl libssl-dev libc6-dev clang libclang-dev ca-certificates
sudo apt install git
git --version
Note: Anytime you use a git clone
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.
sudo snap install yq
curl -fsSL https://get.docker.com -o- | bash
sudo usermod -aG docker "$USER"
exec sudo su -l $USER
docker run --privileged --rm linuxkit/binfmt:v0.8
docker buildx install
docker buildx create --use
curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
cargo --version
git clone -b latest --recursive https://github.com/Start9Labs/start-os.git && cd start-os/core && ./install-sdk.sh
# initialize sdk
start-sdk init
# verify install
start-sdk --version
sudo snap install deno
Check your environment setup by building a demo project and installing it to StartOS.
git clone https://github.com/Start9Labs/hello-world-wrapper.git
cd hello-world-wrapper
hello-world.s9pk
make
Settings -> Sideload Service
hello-world.s9pk
from your filesystem to installServices -> Hello World
and click "Start"The package file produced by this process has a s9pk
extension. This file is what is installed to run a service on StartOS.
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:
After coding the build steps, build the Docker image using docker buildx
, replacing the placeholder variables:
docker buildx build --tag start9/$(PKG_ID)/main:$(PKG_VERSION) --platform=linux/$(PLATFORM) -o type=docker,dest=image.tar .
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
file, which defines:
instructions.md
file:
LICENSE
file:
icon.png
file:
MAKEFILE
:
Dockerfile
:
docker_entrypoint.sh
script:
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):
start-sdk pack
# replace PKG_ID with your package identifier
start-sdk verify s9pk $(PKG_ID).s9pk
The verification step will provide details about missing files, or fields in the service manifest file.
That's it! You now have a package!
make
command from the root folder of your wrapper repository to execute the build instructions defined in the MAKEFILE
Settings -> Sideload Service
<package>.s9pk
from your filesystem to installtouch /etc/embassy/config.yaml
echo "host: <IP_ADDRESS_REPLACE_ME>" > /etc/embassy/config.yaml
# login with master password
start-cli auth login
start-cli package install <PACKAGE_ID_REPLACE_ME>.s9pk
Services -> <Service Name>
and click "Start"The s9pk
file can be uploaded for distribution to any website, repository, or marketplace. You can also submit your package for publication consideration on a Start9 Marketplace by emailing us at submissions@start9labs.com or by contacting us in one of our community channels. Please include a link to the wrapper repository with a detailed README in the submission.
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:
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.
Check out the specification here.
Have a question? Need a hand? Please jump into our Community, or our Matrix Community Dev Channel.
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 start-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
start-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
s9pk
- the file extension for the packaged service artifact needed to install and run a service on StartOS