// to display images directly on GitHub
ifdef::env-github[]
:encoding: UTF-8
:lang: en
:doctype: book
:toc: left
:imagesdir: ../../images
endif::[]

////

    This file is part of the PacketFence project.

    See PacketFence_Developers_Guide.asciidoc
    for authors, copyright and license information.

////

=== Packer

To build PacketFence, we use link:http://packer.io[Packer] to create link:https://github.com/orgs/inverse-inc/packages[container images] that are then used in a GitLab pipeline.

=== Anatomy of Packer template

PacketFence rely on link:https://gitlab.com/Orange-OpenSource/gitlab-buildpkg/[gitlab-buildpkg images] to run GitLab pipeline with
link:https://gitlab.com/Orange-OpenSource/gitlab-buildpkg-tools[gitlab-buildpkg-tools]. Packer
template ([filename]`pfbuild.json`) use these images as base to build
inverse-inc container images.

==== Custom build dependencies

To start building PacketFence, we need to install specific things in images
like:

* custom repositories and GPG keys to install RPM or DEB packages at build time
* install and configure upstream softwares necessary to build PacketFence if we can't use packages

We use Ansible and shell scripts to cover these steps. It's possible because Python is already
installed in link:https://gitlab.com/Orange-OpenSource/gitlab-buildpkg/[gitlab-buildpkg images].

==== Build dependencies in packages specs

Build dependencies need to be install in container images before starting build
process. We rely on [package]`gitlab-buildpkg-tools` to automatically install
those dependencies based on packages specifications file. Consequently, all
build requires need to be define in packages specifications file.

==== Golang environment

We use Packer to set up a Golang environment in order to build Golang binaries in container images.

We also set environment variables in container images, using `ENV` directives, to simplify usage of [command]`go` commands.

==== Clean up

To make container images lightweight, we make a clean up at end of the process.

=== How to build container images ?

Container images are built inside a GitLab pipeline.

==== Prerequisites

.Install following softwares:
* http://packer.io/intro/getting-started/install.html[Packer] (>=1.6.5)
* https://docs.docker.com/install/[Docker]
* Ansible (>=2.10)

==== Makefile

Because we run build inside a GitLab pipeline, many environment variables can
be set to change build behavior. A [filename]`Makefile` and a wrapper are provided to
simplify creation of a new container images based on environment variables.

.Example usage of Makefile
[source,bash]
----
 DOCKER_TAGS=feature-pfconfig-container \
REGISTRY_USER=InverseBot REGISTRY_PASSWORD=REDACTED \
REGISTRY=ghcr.io REGISTRY_URL=${REGISTRY}/inverse-inc/packetfence \
make -e -C ci/packer build_img_docker_pfbuild
----

=== Troubleshooting

You can troubleshoot issues in Packer builds by setting environment variable `$PACKER_LOG` environment variable to `1`.
