Articles

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.

list the catalog
# 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      valid

Each 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:

the steps of an installation
$ 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-installed

The pool and project in the paths are those of this example. What each step does:

  1. 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.
  2. Start it. The jail gets its address on the network lan.
  3. Install the package from the host. pkg -r installs into the jail's root, from the repository the host is configured with.
  4. 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 nginx tries again.
  5. Refresh the library cache. pkg -r does not run it inside the jail, so the installer does.
  6. Record the version. The installed version becomes the label jailops.app.version.
  7. Enable the service in the jail's /etc/rc.conf.
  8. Run the setup commands of the definition, as plain argv, with no shell. For nginx they copy the default site into place.
  9. Start the service with service nginx start in the jail.
  10. Check that it answers. An HTTP request to port 80 must return 200 within 30 seconds.
  11. Take a snapshot of every dataset of the jail, named app-installed.

The installation

The same command, without the flag.

install, then look
$ 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.

The install dialog for Forgejo in the JailOps host console in dark theme while it installs: step 7 of 12 with a progress bar, and the steps done so far ticked off. Demo data.The install dialog for Forgejo in the JailOps host console in light theme while it installs: step 7 of 12 with a progress bar, and the steps done so far ticked off. Demo data.
Installing Forgejo from the console, step 7 of 12. Demo data.

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/www in 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 reload applies it.
  • The logs are /var/log/nginx/access.log and error.log. Read them from the host, without a shell in the jail:
the logs of 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:

roll back
$ jailops jail rollback nginx --all --snapshot app-installed

Because 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

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.