jails AppJail v5.5.0 released: OCI migration, daemonless.io integration, Secrets, and a new Getting Started guide

DtxdF

DtxdF

Developer
Over the years, I've used AppJail images as a way to distribute jail snapshots for deterministic deployment, even before OCI was available on FreeBSD. This worked well, but the problem is that I have to build them somewhere, and I used to do that on my own computers, powered by Buildbot. The problem was that, as I added more and more images, my disks were failing faster and faster.

This year, I heard about daemonless.io when a user sent me a link after I described the problem above, and I think the project is incredible. I believe that integrating with daemonless.io will help both projects improve, since, although AppJail implemented support for deploying jails using OCI images from the very beginning, when OCI was first implemented in FreeBSD, I needed images to battle-test appjail-oci(1).

After conducting more and more tests and once the appjail-oci(1) command reached a level of maturity, I decided to migrate AppJail images in AppJail-makejails to OCI images. The OCI images in AppJail-makejails are built similarly to how they're built on daemonless.io, using dbuild as the build engine, and are distributed to the GitHub registry. The migration began on June 24, 2026, and ended on August 27, 2026.

My main goal in creating OCI images is for them to be built exactly the same way as in upstream. You can compare:

And there are many more. Of course, I had to adapt the work done on upstream to account for the differences between Linux/Docker and FreeBSD, but in most cases it was very straightforward.

Some images required Docker Secrets, and since this feature wasn't available in AppJail, I implemented it. For now, rage/age is the only backend implemented, but I plan to add Hashicorp Vault in the next release.

After working on all of this, I think it was necessary to improve the Getting Started guide to give new users a quick way to get started. But to make things much simpler, I've written a script that allows you to easily initialize the host, explains the basics of AppJail, shows some slightly more advanced use cases (like Makejails), and introduces The Ephemeral Concept. This guide also shows you how to deploy a FreeBSD VM using bhyvemgr to test AppJail.setup in a safe manner. Any feedback is welcome.

There are two other things worth noting:

  • I've added support in appjail-fstab(1) for mounting sockets. By this I mean mounting individual sockets. See this and the release notes for more details.
  • A new AppJail hook has been added to EXAMPLESDIR for cases where you want to load a kld. Some examples include deploying a Linux app inside a FreeBSD jail, deploying WireGuard, or (which was the main motivation) deploying Sylve.
Release: https://github.com/DtxdF/AppJail/releases/tag/v5.5.0

Container Stores: https://wiki.freebsd.org/Containers#Container_Stores
 
I discovered AppJail this year via daemonless.io . I built a dedicated jail host for AppJail so that I could become familiar with it. Sadly, I didn't get up to speed quick enough. When I had to create working systems to a deadline, I went back to what I know, iocage+Ansible on FreeBSD and Docker on Void Linux. I am not done with AppJail. I will go back to it. I probably would have settled in quicker if I had a worked example that was closer to my use cases to follow. The two main use cases I have are:
1. Running jails and containers on a VPS with virtio for network and storage
2. Running jails and containers on a physical host where the jails/containers use a variety of VLANs that are present on the host interface.

AppJail wasn't the only learning difficulty for lack of time that I had this summer. I also struggled with bridging and VLANs in the 'new' FreeBSD 15.x way. When documentation is not dated or does not refer to release version numbers, it is difficult to determine what parts of the available documentation are still relevant and what is now obsolete. Actual proven working config files are often more useful than documentation that doesn't contain sufficient detail.

I am looking forward to trying out AppJail's mounting of sockets. Thanks for adding this really useful feature.
 
You must log in or register to reply here.
Back
Top