An app is a piece of software that ORC8R installs and runs on your nodes. Instead of logging into each machine and setting things up by hand, you attach an app to a pool and ORC8R installs it on every node for you. This page explains how to use existing apps and, for the more technical reader, how to author your own.
How apps get onto nodes
You choose apps when you request nodes. In the Choose apps step of the request wizard (see Pools):
- Click Add Application.
- Pick an app from the catalog.
- Choose a version, and fill in any settings the app asks for.
Every node created for that pool then installs the apps you selected. If you add none, nodes start with just the agent. Some apps run a task once and finish (for example, installing a package); others run continuously as a service.
Configuring apps for a project or organization
You can set defaults for an app so that everyone requesting nodes gets sensible values without having to fill them in each time. Open a project and go to Project Apps (or an organization and go to Organization Apps). For each app you can:
- Pin a version so new nodes always use a known-good release.
- Set default values for the app's settings.
- Lock settings so users cannot change them at request time.
- Disable the app so it does not appear in the catalog for that project or organization.
Settings flow from broad to narrow: an organization's defaults apply to all its projects, and a project can add its own on top. If your organization disables an app, a project inside it cannot turn it back on.
Authoring your own app
If the app you need does not exist, you can build one. An app is packaged as a standard OCI artifact (the same kind of package used for container images), so it can be stored in an ordinary registry. You describe the app in a small file called artifact.yaml, then build it with the orc build command.
What goes in artifact.yaml
The recipe has a few top-level parts:
- annotations — the app's name and description (
org.opencontainers.image.titleandorg.opencontainers.image.description). - config — how the app behaves: its settings and its lifecycle steps (see below).
- files — any scripts or binaries the app ships with.
- platforms — which operating systems and architectures the app supports (for example, Linux on amd64 and arm64).
Inside config, you describe the app's settings under params, and its lifecycle under phase names. The phases are install, start, drain, stop, finish, and uninstall; you only include the ones you need. A start command that keeps running makes the app a long-lived service; an install command that finishes makes it a one-time task.
Each setting under params has a title, a description, and a placeholder to guide the person filling it in. When a node runs the app, each setting is passed to your commands as an environment variable with an upper-cased name — so a setting called packages arrives as PACKAGES. Settings can be marked required, offered as a fixed list of choices, or marked sensitive so their values are stored securely rather than in plain text.
A real example
This is the built-in apt app, which installs Debian or Ubuntu packages. It has one required setting, packages, and runs a script during the install phase:
artifactType: application/vnd.orc8r.app.v1
annotations:
org.opencontainers.image.title: apt
org.opencontainers.image.description: Install Debian/Ubuntu packages via apt-get
config:
params:
type: object
required: [packages]
properties:
packages:
type: string
title: Packages
description: Space-separated package names (e.g. git curl htop)
placeholder: "curl git vim"
install:
command: sh install-apt.sh
files:
- install-apt.sh
platforms:
- os: linux
arch: amd64
- os: linux
arch: arm64
When someone adds this app to a pool and types curl git vim into the Packages field, every node runs install-apt.sh with PACKAGES set to curl git vim, installing those packages.
Discovering versions
An app can declare where its versions come from — for example, GitHub releases — so ORC8R can list the available versions for people to choose from, and you can set a default. This lets an app track upstream releases without you republishing it each time.