Packages
A package bundles everything a service or a scope needs to run: its specification, the actions and links that go with it, and the worker image that implements them. The bundle is versioned as a whole, so the code in the image always reads the specification it was released with.
This section covers the packages that carry a service or a scope. The package model is more general than that: a package bundles components of several kinds, and other kinds of packages, with components of their own, get their own guides.
Publishing and installing are separate verbs
Think of a package the way you think of a library: a maintainer publishes it, and a project installs a version.
- Publishing creates the specification in the publisher's organization and adds a new revision to the package. Each revision pins the exact specification, actions, links and image of one release.
- Installing makes a package available in your organization, at the NRN you choose, pinned to one version. New services or scopes created there use that version.
Nullplatform publishes its sample services and scopes this way. You can also publish packages of your own and install them inside your organization.
What an installation gives you
Once a package is installed, its specification shows up in Platform settings next to the ones you wrote, marked as read-only and with the installed version. Developers create services or scopes from it like from any other specification.
You can't edit the specification, its actions or its links: they belong to the publisher. What you own is everything around them, such as the agent channel that runs the actions, the cloud permissions the worker uses, and, for scopes, the scope type and its settings.
Versions and the default
A revision is immutable. Each release of the package publishes a new one, versioned like the release, and the ones before it stay as they were. The package also has a default version: the one an installation gets when it doesn't pin a version. A stable release becomes the default; a prerelease is published without moving it, so you can install it by version to try it.
Upgrading an installation means moving its pinned version. Nothing moves on its own: services and scopes created from the previous version keep running until you upgrade.
Global packages
A package published to every organization is a global package. The sample services and scopes nullplatform maintains are published this way, under slugs with the np- prefix, such as np-aws-s3-bucket or np-aws-lambda. The prefix keeps them apart from any copy of the same specification you registered yourself, so both can live in one organization.
When you install a global package, you don't get a copy of its specifications: you read the publisher's, and each new release reaches you as a version you can move to.
Next steps
- Install a package: set up the layers an installation needs, pin a release, and upgrade
- Roll out a version: move the services and scopes you already have to another version, in waves
- Sample services: the services nullplatform publishes as global packages
- Services: what services are and how they work
- Scopes: what agent-backed scopes are and how they work
- API reference: the Package and Package installation endpoints