focker/docs/Basic_Usage_Guide.md

# 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.