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.
- Start
jailops app new NAMEwrites a commented starter;jailops app export JAILdrafts one from a jail you tuned by hand. - EditPackages, services, ports, data, setup, health check, notes. Format version 1.
- Validate
jailops app validate NAME.yaml: the daemon's own checks, offline, no root. - Install locallyDrop it into
/usr/local/etc/jailops/apps, thenjailops app install NAME. Listed at once, markedlocal. - Pull request
NAME.yamlandNAME.svginmain/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]writesNAME.yaml, a commented starter definition, andNAME.svg, an icon placeholder.TODOmarkers 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, markedlocal. 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.
# 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
UNVERIFIEDin a comment, as the catalog does. version:states the package version you wrote it against.
Works without hands
jailops app installon a fresh host gives a running service, with nothing to do in between.setupgives 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.
notessay what the person must do next: passwords, domain, TLS, firewall. Nothing is generated, and no secret is in the file.expose: trueonly for a port meant for the outside.
What featured means
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.
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 newjailops-appsversion is refused.A person reads it against the package
Names, paths, owners and ports against what the package installs; every
setupcommand; 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.Merging ships it
Merging to
masterpublishes the new, signedjailops-apps. No JailOps release is involved; hosts get the app with their nextpkg upgrade.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.