From ec645a40ae51a8c9242256407aec05cda2078b52 Mon Sep 17 00:00:00 2001 From: Stanislaw Adaszewski Date: Sat, 30 May 2020 09:40:30 +0200 Subject: [PATCH] Add Basic_Usage_Guide.md. --- .gitignore | 1 + README.md | 5 +- docs/Basic_Usage_Guide.md | 135 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 docs/Basic_Usage_Guide.md diff --git a/.gitignore b/.gitignore index d8329a9..5ac2c2d 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ __pycache__ /*.shar /example/gitea/x .pytest_cache/ +.coverage diff --git a/README.md b/README.md index 206f3f6..dad6e8a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,10 @@ ## Introduction -Focker is a FreeBSD image orchestration tool in the vein of Docker. +Focker is a FreeBSD image orchestration tool in the vein of Docker. This +page contains a detailed reference of Focker's functionality. If it is your +first time using Focker, please refer to the +[Basic Usage Guide](docs/Basic_Usage_Guide.md) first. ## Table of Contents diff --git a/docs/Basic_Usage_Guide.md b/docs/Basic_Usage_Guide.md new file mode 100644 index 0000000..b5524b4 --- /dev/null +++ b/docs/Basic_Usage_Guide.md @@ -0,0 +1,135 @@ +# Focker Basic Usage Guide + +## Prerequisites + +In order to get started, you have to prepare a base image for usage with Focker. +In order to do so, you can use the `focker bootstrap` command. + +`focker bootstrap` has the following syntax: + +``` +usage: focker.py bootstrap [-h] [--tags TAGS [TAGS ...]] [--empty] + +optional arguments: + -h, --help show this help message and exit + --tags TAGS [TAGS ...], -t TAGS [TAGS ...] + --empty, -e + ``` + +If you use the `--empty` switch, it will create an empty image. This is used +principally for testing and unless you want to set up your image manually, it is +recommended to run `bootstrap` without the `--empty` switch. + +The `--tags` parameter lets you specify the tags that the resulting image will +receive. If you do not specify this, the image will be tagged with `freebsd-latest` +and `freebsd-x.y` where `x.y` will be the major and minor version obtained +from a call to `freebsd-version`. + +The `bootstrap` command creates a new image and runs `bsdinstall jail` targeting +its mountpoint. It is recommended to install only the base system (no ports, no lib32), +disable all services and do not add any users. The base image will most likely serve as +the starting point for all the other images that you will be building. Pre-made +`Fockerfile` recipes, unless indicated otherwise, will most likely expect a +barebones image as the base. + +It is a good practice to account for a base image that has been created by just +clicking through the `bsdinstall jail` installer. Therefore, many `Fockerfile` +recipes will execute the following steps to disable sshd, sendmail, make syslog +listen only locally, enable clearing of `/tmp` and disable writing to +`/var/spool/clientmqueue`: + +``` +sysrc sshd_enable=NO +sysrc sendmail_enable=NONE +chown root:wheel /var/spool/clientmqueue +chmod 000 /var/spool/clientmqueue +sysrc syslogd_flags="-ss" +sysrc clear_tmp_enable="YES" +``` + +We can now move on and let you try create your first own customized `Fockerfile`. + +## Trivial Example + +At the very basic level, Focker can be used simply as a jail building system. +In order to get started you have to create a new directory: + +``` +mkdir test-focker-build +cd test-focker-build/ +``` + +with a file called `Fockerfile` inside: + +`touch Fockerfile`. + +Using your editor of choice (`ee` is a good one), you can now put a trivial +directive in `Fockerfile`: + +``` +base: freebsd-latest +steps: [] +``` + +The `base` directive determines the starting point for your future image. +A starting point is simply a pre-existing image. We will call this image +the parent image. The chain always terminates with an image that doesn't have +a parent. Such an image has to be created manually, by using `focker bootstrap` +or perhaps transferred using `zfs send`/`zfs receive` combo. + +Now you are ready to build your first image. Run: + +`focker image build .` + +The `focker image build` command has the following syntax: + +``` +usage: focker.py image build [-h] [--tags TAGS [TAGS ...]] [--squeeze] + focker_dir + +positional arguments: + focker_dir + +optional arguments: + -h, --help show this help message and exit + --tags TAGS [TAGS ...], -t TAGS [TAGS ...] + --squeeze, -s +``` + +As you can see, in our call `focker image build .` we have specified only the +`focker_dir` parameter. It tells the Focker which directory contains the +Fockerfile and potentially any additional files that you would like to include +in your build (we will get to this later). + +You will see an output similar to the following: + +``` +Waiting for /var/lock/focker.lock ... +Lock acquired. +poolname: zroot +fname: ./Fockerfile +spec: {'base': 'freebsd-latest', 'steps': []} +base: zroot/focker/images/e4d5685@1 root: zroot/focker/images +``` + +and if you run `focker image list` you will discover that you are still +stuck only with your pre-existing base image. Why is that? + +Since we have specified no `steps` or more precisely we have specified +an empty list of steps, the resulting image has the same checksum as the +base image. This is the case since no modifications have been made and the +image content is identical. To observe an effect, we could still run: + +`focker image build . -t test-build` + +This will instruct Focker to add a new tag to the resulting image. If you +run `focker image list` now, you should see an output similar to: + +``` +Tags Size SHA256 Base +-------------------------------------- ------ -------- ------- +freebsd-latest freebsd-11.2 test-build 266M e4d5685 - +``` + +Congratulations! Your first image has been tagged. We can now start +filling the `steps` list to create something more useful.