Service Packaging¶

Dependencies - Recommended¶

These tools may or may not be necessary, depending on your environment and the package you are building.

• Code Editor (IDE) - We recommend Visual Studio Code

Dependencies - Required¶

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

  curl -fsSL https://get.docker.com | bash
  sudo usermod -aG docker "$USER"
  exec sudo su -l $USER
  

  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).

  docker run --privileged --rm linuxkit/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:

  docker buildx install
  docker buildx create --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.

  git clone https://github.com/Start9Labs/start-os.git && \
   cd start-os && make frontends && mkdir -p ./frontend/dist/static && \
   cd ./backend && ./install-sdk.sh
  

  Initialize sdk & verify install

  embassy-sdk init
  embassy-sdk --version
  

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

  Ubuntu:

  sudo snap install deno
  

  Other *nix:

  curl -fsSL https://deno.land/x/install/install.sh | sh
  

Build a Dockerfile¶

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:

• Download an image from Docker Hub

• 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 docker buildx, replacing the placeholder variables:

docker buildx build --tag start9/$(PKG_ID)/main:$(PKG_VERSION) --platform=linux/arm64 -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.

Create File Structure¶

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)

  • Port mappings (i.e. interfaces)

  • Check out the Hello World example to see line-by-line details

• instructions.md

  • Instructions for the user

  • Appears as a menu item in the service page UI

• LICENSE

  • The Open Source License for your wrapper

• icon.png

  • The image that will be associated with the service throughout the UI, including in a marketplace

• MAKEFILE

  • Build instructions to create the s9pk

  • Example MAKEFILE

• prepare.sh

  • A script that setups up the build environment for a Debian system so that Start9 can verify the build process upon submission.

• Dockerfile

  • A recipe for service creation

  • Add here any prerequisite environment variables, files, or permissions

  • Examples:

  • Using an existing docker image

  • Implementing a database

  • Using a submodule

• docker_entrypoint.sh

  • Starts and governs the operation of a service container

  • Gracefully handles container errors and user preferences, i.e. username/password, SIGTERMs

  • Examples:

    • Robosats

    • Photoview

    • RTL

Format Package¶

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-sdk pack
  

• Verify the s9pk (replace PKG_ID with your package identifier):

  embassy-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!

Scripting on StartOS¶

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.

Check out the specification here.