Community

Build an app. Share it.

An app in the JailOps catalog is one short YAML file: the packages, the services, the ports, where the data lives and how to tell that it runs. If a FreeBSD package runs as a service, you can turn it into an app on your own host, and into a one-command install for everyone with one pull request.

The idea

Every good app in the catalog started as somebody's jail that worked. The path from there to the catalog is short on purpose.

  • Try it on your host

    A jail of its own, packages from the host's repository, a snapshot to go back to. Breaking things costs you one rollback.

  • Make it work, then write it down

    The owners, the knobs, the setup steps, a health check that proves it answers. What you did by hand becomes the definition.

  • Send a pull request

    One file and an icon in the packages repository. CI checks it, a person reviews it, and once it is merged, every host gets it with its next pkg upgrade.

What you contribute to

What the catalog is, and why it is signed

The catalog is a set of app definitions, one YAML file per app, delivered as an ordinary FreeBSD package, jailops-apps, from pkg.jailops.net. The package installs the files under /usr/local/share/jailops/apps, and the JailOps daemon reads them from there. It reads local files only and never fetches a catalog from anywhere.

That is why the signature matters. A definition decides which packages go into a jail, which commands run in it as root during setup, and which ports a service listens on. Because the catalog arrives as a signed package, nothing in it changes on a host without a package operation the operator ran, from a repository the host already trusts. Your app inherits that: once merged, it reaches hosts the same verified way as JailOps itself.

Every definition is validated whenever it is read. One that fails is listed with the reason and can never be installed, and the others are not affected.

Five steps

The loop

From an idea to a merged app. You will go round steps two to four a few times; that is the point.

  1. Startjailops app new NAME writes a commented starter; jailops app export JAIL drafts one from a jail you tuned by hand.
  2. EditPackages, services, ports, data, setup, health check, notes. Format version 1.
  3. Validatejailops app validate NAME.yaml: the daemon's own checks, offline, no root.
  4. Install locallyDrop it into /usr/local/etc/jailops/apps, then jailops app install NAME. Listed at once, marked local.
  5. Pull requestNAME.yaml and NAME.svg in main/jailops-apps/apps, the version raised. CI validates it.

Authoring

The tools

Everything runs on your own host or laptop. Nothing is uploaded anywhere until you open the pull request.

  • jailops app new NAME [--package PKG[,PKG...]] [--service NAME] [--port N[/proto]] [--category C] [--dir DIR] writes NAME.yaml, a commented starter definition, and NAME.svg, an icon placeholder. TODO markers make validation fail until you have replaced every one.
  • jailops app export JAIL [--project P] [--to FILE] drafts a definition from a jail that already works: its installed packages, enabled services, listening ports, data volumes, the names of changed configuration files and its recent logs. Never secrets.
  • jailops app validate PATH... checks files or whole directories with the daemon's parser and validator, without a server, a network or root.
  • The local apps directory, /usr/local/etc/jailops/apps (apps.local_dir): a definition dropped there is listed and installable at once, marked local. A local definition with the name of a packaged one wins, so you can try a fix to a catalog app before you send it.

These commands run as root on the host.

from nothing to an installed app
# jailops app new memcached --package memcached \
    --service memcached --port 11211/tcp --category database
# edit memcached.yaml until no TODO is left
# jailops app validate memcached.yaml
# cp memcached.yaml memcached.svg /usr/local/etc/jailops/apps/
# jailops app list memcached
# jailops app install memcached --network lan --storage default

# or start from a jail that already works
# jailops app export cache --project web --file memcached.yaml

Before you send it

The quality bar

A catalog app is a promise: one command, and the service runs, correctly, in a jail of its own. These are the things a reviewer will check.

  • True to the package

    • Package, rc.d and knob names, ports and paths as the FreeBSD package installs them, read from the package, not from memory or another system's documentation.
    • A comment at the top says where the facts come from. What you could not check is marked UNVERIFIED in a comment, as the catalog does.
    • version: states the package version you wrote it against.
  • Works without hands

    • jailops app install on a fresh host gives a running service, with nothing to do in between.
    • setup gives directories to their user and does what the package leaves to post-install steps: plain argv, absolute paths.
    • Every path that holds state is in data, so it lands on a volume that survives upgrades and is backed up.
  • Honest about itself

    • A health check whenever a service starts, and one that proves the service answers: a query, a ping, a page, not just an open port when a better check exists.
    • notes say what the person must do next: passwords, domain, TLS, firewall. Nothing is generated, and no secret is in the file.
    • expose: true only for a port meant for the outside.

Featured is not a key in the definition: it is how we treat an app. The apps of the catalog each have a block of their own in the end-to-end test of the JailOps repository, which installs the app on FreeBSD and checks that it really answers: a query for PostgreSQL, PONG from Valkey, the SMTP and IMAP greetings for the mail server. That is the bar for being shown there. A contributed app can get there too: send the check with it, and keep the app current when its package moves.

After you send it

How reviews work

Nothing is merged automatically, and nothing is published without a person.

  1. CI checks it

    The packages repository builds the JailOps client at the release it packages and runs jailops app validate main/jailops-apps/apps, so the definition must be valid for the daemon hosts actually run. A change to the catalog without a new jailops-apps version is refused.

  2. A person reads it against the package

    Names, paths, owners and ports against what the package installs; every setup command; whether the health check proves anything; whether the notes tell the truth. Expect questions in the pull request; they are how the bar stays where it is.

  3. Merging ships it

    Merging to master publishes the new, signed jailops-apps. No JailOps release is involved; hosts get the app with their next pkg upgrade.

  4. Newer format, newer daemon

    A definition that needs a key or category only a newer JailOps knows is listed as invalid on older hosts, with the reason, until they upgrade. The other apps are not affected.

Where to ask

About a definition, a package or the catalog: open an issue or a draft pull request in the packages repository. A draft early is better than a perfect one late; say what you could not get to work. About JailOps itself, the installer or the format: the JailOps issue tracker. Problems you hit while trying are probably on the help page already.

The contributor guide is CONTRIBUTING.md in the packages repository.

Found a security problem in JailOps or in a package? Report it privately: how to report.

Start with a small one

Your first app, from a package you know.

The tutorial turns the FreeBSD memcached package into an app, from the first line of YAML to the pull request.