◜PFC◞ — Pain Free Containers

Imagine three seemingly simple problems — and let us suppose they are both applicable to your current situation (actually, very probable) and you need to solve them fast.

Prerequisites: you're using Docker, you have an image/container, of about 2Gb in size and you have a co-worker who, unlike you, uses FreeBSD (or MacOSX / Windows / Raspberry Pi OS...) instead of Linux and isn't quite keen on setting up a Virtual Machine. These are your problems, then:

1. How do you make it work for your co-worker without him getting angry at you?
2. How do you update the image without re-sending it every time a small change is introduced?
3. How do you keep your co-worker happy be allowing him his own .dotfiles and environment within the container, while also keeping the important parts rolling and working the same way?

Before you go on raging about how "who cares about FreeBSD" let us present our case of recipes, which would be a much better solution even for two identical Linux hosts running Docker, let alone anything different.

A non-perverse solution to it is NOT to write a Dockerfile (especially, that Dockerfiles are only supported by Docker and maybe Podman). It is to write a script or, perhaps, a compiled program that would make the necessary changes to the container. You can then keep on pile new scripts on top, each one either with no dependencies on other the previous ones or some. And that we'll call recipes.

What is a recipe?

A recipe is single executable (or not?) file, written in any language of your choice. Its job is to do things to the target container, such that the container then works in a particular way. For instance, so it can run TensorFlow or Ruby On Rails 7 or whatever. Maybe it has some more complex stuff that needs to be done to it; and maybe your container gets more complex over time. The complexity and structure of the recipe-scripts are both up to you. ◜PFC◞, of course, will provide some basic ones that cover the most popular cases.

To demonstrate what a typical standalone recipe may look like, let's first, let's one. It'll do two things: install Vim and nginx. We'll write it in Bash for convenience, but you can actually write it in any language.

This script will run inside the container and after its completion the container becomes what you want it to be. The advantage of using PFC-recipes instead of Dockerfiles would be that you can do ANYTHING you'd do with any script in any language AND have additional help of the pfc command itself, providing cross platform-functionality for various OS living inside containers themselves.

Applying recipes

It's easy to apply a recipe (which can be done from both the host or the guest (the latter — so long as made the recipe file available from within the guest file system). You just have to type: pfc recipe [FILENAME] or, if you have a special dedicated directory, which holds all the recipes for a particular type of image(s) and you know you want to apply them all, just type pfc recipe

The trick there, of course, is the order in which they shall be applied and the dependencies they shall have. Luckily, ◜PFC◞ can help you with both.

• The order is determined by the numbered prefix of the recipe filenames, much like it's very often done with database migrations. You can consecutive integers or timestamps, it doesn't matter.
• The dependencies are trickier, but only on the inside, not for the user: each container holds the information about all of the applied dependencies inside of itself. Thus, while writing your own recipe, you can make sure it doesn't run unless those dependencies are met, by putting the following code at the top of the file:

This basically tells ◜PFC◞ two things: your current recipe belongs to a group of recipes called "php8" and that before it's applied it must make sure that all of the available recipes from the "pfc-compat" and the "nginx" groups were applied first.

In fact, you do not need to spell it out the first line at all: if it is omitted, ◜PFC◞ will assume group name from your filename. As for the second line, you may just as well call it when calling the command itself, instead of putting into the file (although, it's not recommended).

The question is, what happens if you don't the dependencies? Which source shall be the authoritative one for getting those? We decided at this point to not get into this subject, as this smells package-management reinvention, but be sure we'll get to it as the feature's about to release. Our goal isn't to reinvent the package management in some obscure form under a different name, but to achieve our goals: allow for easy instances updates, no matter which OS or architecture an instance is being run on.

Creating recipe files automatically

It can be rather time-consuming to do things twice: first to manually install the software that you need and edit config files and then to also program a recipe for that. ◜PFC◞ can assist your here as well. By running pfc recipe --draft-changes it will scout system's history and log files, check inconsistencies and create a draft file for you, which you can later edit just a bit to make sure it didn't include the parts you wouldn't want it to include.

PFC-backend refers to the part which ◜PFC◞ itself serves as an interface. A backend can be as "simple" as Docker, or as complex as remote server running FreeBSD, which, in turn, runs Linux with the help of FreeBSD's bhyve hypervisor, which, in turn, runs Docker. In the latter case our "target" is still Docker containers and images, but ◜PFC◞ needs to be able to penetrate all these levels seamlessly, with the very same interface you'd use in the former, simpler case. So how does it do it? Or, rather, what do you, as ◜PFC◞'s user, must do in order to achieve that goal? Let's look at a few simple commands:

The first line of this code switches ◜PFC◞ into a mode, when all of its commands would go through your server that can be accessed by its ip address 11.22.33.44 — this mode will persist even after you reboot your local machine until you type pfc -c local (where -c is a shorthand for context, of course).

After you're in that remote mode, you can use ◜PFC◞ as if it was your local machine. More importantly, none of it has to be installed on your remote system, apart from the FreeBSD itself. ◜PFC◞ will install bhyve, install ubuntu 22.04 onto it, install Docker on it, install the default image and make it PFC-compatible. You could, theoretically, had made this command a bit more complicated, specifying more details, but, perhaps, what's shown here would suffice for now.

The second and the third commands are familiar to you already: they, list images and create/start/connect to an image called mysite.www.var And all of these layers are penetrated for you each time, automatically.

There's more: you don't have to type this every time you want to switch context. Instead you can your context an alias, either while you're in it or while you're just switching into it:

Then, you can switch between the contexts easily:

Shall we take a look at another example employing, say, a Linode API to create containers, instead of using particular container engine?

The second command will create a new Linode instance with Ubuntu 22.04 and connect you to it.

If you'd like to connect software to your instances, you'd need minimum some information, such as ip-address and a port. Ports can be especially tricky if you have layers of various VMs stacked-up upon each other, so ◜PFC◞ simplifies it for you by providing all the necessary information if you type this one command:

or if you're not in the context you need to be, type the following instead:

You shall then be presented with the following output:

The last line is your way through: direct connection cannot be established, thus it shows you the information you need, such as port number — 18011 in this case — and you'll have to use the correct ssh-key & username to connect, which is what that line presents you with as well. It gets you through all the way to LAYER (c).

There are many cases that can made for ◜PFC◞ performing its own backups. OF COURSE you should be doing your own backups, be it your local machine or a remote server. OF COURSE PFC-backups isn't something you have to use. But since it'll be there anyway, let's try them out — especially now, equipped with the knowledge of how easily ◜PFC◞ can switch contexts.

First, let's establish something very important...

It doesn't literally copy containers

Suppose you wanted to perform backups every hour. You wouldn't want ◜PFC◞ to copy all these 2Gb-or-more containers over the network, let alone disk-rewrites, nope. ◜PFC◞ uses plain old rsync to only sync the changes in containers that were made since the last backup. Besides, it makes no sense to copy the container if the architecture on your local machine is different and you'd want to run it anyway if your remote environment goes down. Thus, a clever combination of recipes and rsync does the job under the hood.

Here's an example of a command performing a manual backup of all PFC-instances from your remote server onto your local machine:

And here is an example of the opposite: we're backing up all of your local PFC-instances onto a remote machine:

You can back-up from one remote to another and even include multiple backup targets — including your local machine:

Quite clearly, you wouldn't want to do it all by hand, so you can use another command, which would do all the crontab mambo-jumbo scheduling for you:

And, of course, you can hand-pick containers to be backed up.
Perhaps, not all of them deserve to be backed up after all...

Having done that, you can simply "roll-out" and start your container on your backup-target — local or remote — machine the usual way, as if nothing happened:

Honestly, do you like it? Consider funding us by donating then.

The PFC-toolset allows you to deploy both standalone as well as orchestrated projects. We've also decided to have a separate standalone command for it — pfd, which, again, is a shortcut for pfc --deploy.