From catalog to running service in one command
Installing nginx from the JailOps app catalog, step by step: what jailops app install does, where the data, the configuration and the logs end up, and how to go back to the fresh installation.
The catalog
A package of plain files.
This walk-through starts on a host that already runs JailOps, with a project web, a network lan and the storage default, as in the quick start. The catalog comes with the jailops package, so it is there after the install:
These commands run as root on the host.
# jailops app list -c name,category,version,status
NAME CATEGORY VERSION STATUS
forgejo devops 16.0.6_1 valid
nginx web 1.30.6,3 valid
postgresql database 18.6 valid
prometheus monitoring 3.15.0_2 valid
valkey database 9.1.2 validEach app is a YAML file under /usr/local/share/jailops/apps. The daemon reads those files and nothing else; it never fetches a catalog. jailops app info nginx prints the whole definition: packages, services, ports, data, configuration, logs, setup commands, health check and resource hints.
The plan
Look before you install.
--dry-run asks the server for the steps and creates nothing:
$ jailops app install nginx --network lan --storage default --dry-run
Dry run: nothing was created. Installing app nginx as jail nginx would do:
01 create-jail: create thin jail nginx from freebsd-15-1 with 1 data volume(s) and the labels jailops.app, jailops.app.hash
02 start-jail: start nginx
03 install-packages-ports: pkg -r /zroot/jailops/projects/web/jails/nginx/root install -y nginx
04 set-up-shell: install bash unless it is there (pkg -r /zroot/jailops/projects/web/jails/nginx/root install -y bash); write the bash prompt /usr/local/etc/profile.d/jailops-prompt.sh and source it from /usr/local/etc/profile and /usr/local/etc/bash.bashrc
05 refresh-library-cache: in the jail: /sbin/ldconfig -m /usr/local/lib
06 record-version: pkg -r /zroot/jailops/projects/web/jails/nginx/root query %v nginx, then label jailops.app.version
07 write-rc-conf: set nginx_enable in /zroot/jailops/projects/web/jails/nginx/root/etc/rc.conf
08 setup-1: in the jail: /bin/mkdir -p /usr/local/www/nginx
09 setup-2: in the jail: /bin/cp -Rn /usr/local/www/nginx-dist/. /usr/local/www/nginx/
10 start-service-nginx: in the jail: /usr/sbin/service nginx start
11 health-check: GET http://<first address>:80/ must answer 200, retried for 30s
12 close-firewall: firewall policy app-nginx (managed by app access): deny every inbound connection until jailops app allow nginx --from SOURCE
13 snapshot: snapshot every dataset of nginx as app-installedThe pool and project in the paths are those of this example. What each step does:
- Create the jail. A thin jail from the FreeBSD image of the newest release the host runs, here
freebsd-15-1; name another with--image. Without any FreeBSD image the command says so and names the two commands that make one. The data path of nginx,/usr/local/www, becomes a dataset of its own, mounted at that path. The labels record the app and the hash of its definition. - Start it. The jail gets its address on the network
lan. - Install the package from the host.
pkg -rinstalls into the jail's root, from the repository the host is configured with. - Set up the shell. bash, from the host as well, and the jail's light blue prompt, as every new FreeBSD jail gets them. If this fails, the installation goes on and the jail says so;
jailops jail shell-setup nginxtries again. - Refresh the library cache.
pkg -rdoes not run it inside the jail, so the installer does. - Record the version. The installed version becomes the label
jailops.app.version. - Enable the service in the jail's
/etc/rc.conf. - Run the setup commands of the definition, as plain argv, with no shell. For nginx they copy the default site into place.
- Start the service with
service nginx startin the jail. - Check that it answers. An HTTP request to port 80 must return 200 within 30 seconds.
- Take a snapshot of every dataset of the jail, named
app-installed.
The installation
The same command, without the flag.
$ jailops app install nginx --network lan --storage default $ jailops app installed JAIL APP VERSION STATE ADDRESSES PORTS nginx nginx 1.30.6,3 running 10.77.0.4 80/tcp,443/tcp $ jailops label nginx jailops.app=nginx jailops.app.hash=sha256:eba3c10e6ba65e642b2503a62b3c4f6f3e11bb247d449f8a9bad619857aa4b4c jailops.app.version=1.30.6,3 $ jailops exec nginx -- grep nginx /etc/rc.conf nginx_enable="YES" $ jailops jail snapshot list nginx NAME WRITTEN AGE COMMENT app-installed 0 B - app nginx as installed
When the command returns, it prints a report: the address with each port, the data, configuration and log paths, the snapshot, and the notes of the definition. If a step fails before the jail first started, the jail is removed again. If a later step fails, the jail is stopped and kept, so you can look inside it before you delete it and try again.
The same from the console
One dialog.
The host console has an Apps page with the same catalog. Install on an app opens a dialog with the jail name, the network, the storage and the limits from the resource hints. Preview steps shows the steps of the dry run; during the installation the list is ticked off step by step, and it ends with the same report, the app-installed snapshot and the rollback command.


Afterwards the Installed tab lists the jail, and the Logs tab of the jail reads its log files. See every screen.
Where things are
Data, configuration, logs.
- The site is under
/usr/local/wwwin the jail, on its own dataset. It is snapshotted and backed up with the jail, and a later upgrade of the jail to a new image generation leaves it alone. - The configuration is
/usr/local/etc/nginx/nginx.conf. After a change,jailops exec nginx -- service nginx reloadapplies it. - The logs are
/var/log/nginx/access.loganderror.log. Read them from the host, without a shell in the jail:
$ jailops jail logs nginx $ jailops jail logs nginx nginx/access.log --tail 50 -f
The jail starts at every boot (boot.autostart), and jailops boot shows where it is in the order. The app is closed after the installation. jailops app allow nginx --from host lets the host in, and then it can fetch the default page from http://10.77.0.4/; from jail:NAME allows a jail of the project (see App access). Publishing it to the outside is up to your firewall and proxy setup for now.
Going back
To the fresh installation.
Whatever you change afterwards, the snapshot app-installed is the state right after the health check passed. One command returns every dataset of the jail to it:
$ jailops jail rollback nginx --all --snapshot app-installedBecause it discards what was written since, the command shows how much that is and asks you to type the jail name first.
The other apps of the starter catalog work the same way. Their full definitions are on the catalog page.
More articles
Jail updates without cron
Replace the nightly script that upgrades every jail: automatic jail upgrades per image, with a health check, a rollback and a record of every run, what they leave alone, and how a new FreeBSD release comes in.
Read the article: Jail updates without cronJail search and shell
Ctrl+K, a few letters, Shift+Enter: find a jail by name, label or app and open its shell. Labels that filter the jail list, bash in new jails, and the jailops command next to every step.
Read the article: Jail search and shellGetting started with the JailOps CLI
Root on the host, the command line and nothing else: install JailOps, build an image, create a network and a jail, reach it by name, snapshot it, open a port and install an app.
Read the article: Getting started with the JailOps CLIJailOps on a netcup server, with IPv6 that stays up
A /64, a router pair and a FreeBSD default that drops their probes. How every jail gets its own IPv6 address on netcup, and the one sysctl that ends the random unreachable alerts.
Read the article: JailOps on a netcup server, with IPv6 that stays upOne small cloud server, many services, solid IPv6
Run your database, web tier and workers on one low-cost server, each jail with its own IPv6 address, and fix the alerts a shared /64 causes with one sysctl.
Read the article: One small cloud server, many services, solid IPv6Write your own app: memcached, from package to catalog
Turn a small FreeBSD package into a JailOps app: the definition line by line, the offline check, a local install, the five traps, and the pull request that puts it in the catalog.
Read the article: Write your own app: memcached, from package to catalogA firewall you can read
Policies, address sets and jails by name (jail:web), each with a comment, so the firewall can be reviewed by someone who did not write it.
Read the article: A firewall you can readPostgreSQL and git, closed except for who needs them
Close a database and a git server, then let in exactly the web jail and the office, with a comment on every entry.
Read the article: PostgreSQL and git, closed except for who needs themProjects are boundaries
A project is a boundary. Another project is an external host, so only addresses cross it, written out on both sides. Why that is simpler to review, and what a project does not isolate.
Read the article: Projects are boundariesThe life of a jail
A jail starts at boot only when you declared it with --autostart. Why JailOps does it this way, how the order is decided, and how to see it with jailops boot.
Read the article: The life of a jailTab completion for jailops
Press Tab and get the names of your jails, networks and firewall policies, even on another host. How to install and turn on completion in bash, zsh and fish.
Read the article: Tab completion for jailopsTest the firewall before you trust it
Ask the firewall whether a connection would pass, and why, before you try it. Read the answer, put it in a script, and know what it cannot tell you.
Read the article: Test the firewall before you trust itSee a connection before it happens
Pick a From and a To, a protocol and a port, press Run, and see the connection flow through the firewall: what passes, what stops it, and which rule decides.
Read the article: See a connection before it happensLimit what a jail can use
Give a jail a ceiling for memory, processes, CPU, disk, firewall states and bandwidth, one command each, and know what happens when it reaches it.
Read the article: Limit what a jail can useStop every jail cleanly when the host shuts down
A host that reboots should stop its databases before it stops the disks. How JailOps stops the jails in order, and how to start them in order again.
Read the article: Stop every jail cleanly when the host shuts downOne line in pf.conf
The host's firewall stays yours. JailOps asks for one line, and everything for the jails lives below it.
Read the article: One line in pf.confWhat the host tells you by itself
A pool that reports an error, an uplink that goes down, a jail that reaches a limit: they show up in the event stream by themselves.
Read the article: What the host tells you by itselfNetworks the host controls
No bridge, no DHCP. The host hands out the addresses, gives each jail a link of its own and is the router, so jails cannot see or impersonate each other.
Read the article: Networks the host controlsVolumes: data that outlives a jail
Keep the data in a volume and the jail disposable. One volume can be attached to several jails, has its own snapshots and its own backup.
Read the article: Volumes: data that outlives a jailBack up volumes once
One copy of a volume, however many jails use it. Leave volumes out when you want to, bring them back with the jail.
Read the article: Back up volumes onceA private Docker registry
A registry of your own with users in a file: one jail, docker-registry and docker-auth, htpasswd for the passwords, the images on a volume.
Read the article: A private Docker registryNames for jails
A jail is reached by its name inside its project: db.shop.internal, or just db. Create a jail and its name is there; delete it and the name is gone.
Read the article: Names for jails
Try it on one server.
Try the console from the screenshots, install on a clean FreeBSD 15.1 machine, or add JailOps to a host you already run.