From 509c78896c9414ac0b30c718adcb0efad67596d1 Mon Sep 17 00:00:00 2001
From: Jonathan Bauer
Date: Thu, 18 May 2017 11:25:33 +0200
Subject: updated README

---
 README.md | 160 +++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 91 insertions(+), 69 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 295e3b0..381e437 100644
--- a/README.md
+++ b/README.md
@@ -10,111 +10,133 @@ Download: https://www.packer.io/downloads.html
 ## Usage
 
 The file 'base.json' contains default variables (VM, SSH) common to all templates,
-and must always be included using packer's '-var-file' option.
-The root password is expected to be in the ROOTPW environment variable.
-The installation procedure will fail without it!
+and should always be included using packer's '-var-file' option. The root password
+is expected to be specified as the ROOTPW environment variable!
 
 Basic usage:
 ```shell
-	ROOTPW=<password> packer build -var-file=base.json <template>
+ROOTPW=<password> packer build -var-file=base.json <template>
 ```
 For the rest of the examples, ROOTPW is assumed to be set in the environment.
 
 ## Usage: Creating base images
 
-Example - Build Ubuntu 16.04.2 LTS template using qemu builder
+#### Example
+Build Ubuntu 16.04.2 LTS template using qemu builder
 ```shell
-	packer build -var-file=base.json -only=qemu ubuntu-16.04-amd64.json
+packer build -var-file=base.json -only=qemu ubuntu-16.04-amd64.json
 ```
-Debug:
+Same with debug output:
 ```shell
-	PACKER_LOG=1 PACKER_LOG_FILE=/var/log/packer.log \
-		packer build -debug -only=qemu -var-file=base.json ubuntu-16.04-amd64.json
+PACKER_LOG=1 PACKER_LOG_FILE=/var/log/packer.log \
+	packer build -debug -only=qemu -var-file=base.json ubuntu-16.04-amd64.json
+```
+A successful build process would generate the disk image as '<builder>/<template>', e.g.:
+```shell
+output-qemu-ubuntu-16.04-amd64/ubuntu-16.04-amd64
 ```
-A successful build process would produce a disk image under:
-	<builder>/<template>, e.g. qemu/centos-7.3-x86_64
 
 Additionally, the manifest post-processor creates a manifest.json file in
 the working directory containing various information about the generated
-artifact, in particular the path to the disk file.
-
+artifact, in particular the path to the disk file which can be easily extracted
+with jq:
+```shell
+jq -r '.builds[0].files[0].name' < output-qemu-ubuntu-16.04-amd64/manifest.json
+```
 ## Usage: Provisioning base images
 
-The packer templates provided by the main repository only create very basic
-disk images. These are meant to be very minimal installations only. Further
-customizations on the base images should be done separately by a provisioner.
-Only the software needed for the provisioners to work should be directly
-installed and configured during the packer build process. Since we focus on
-ansible, only a SSH server and the ansible packages are currently installed.
+The templates provided by this repository only perform minimal OS installations.
+Further customizations on base images should be done separately in
+a provisioning step. These will be developed in the ansible-roles repository and
+will not be further discussed here. The only requirement on the packer build process
+is to install the provisioning software and configure its remote access. Since the focus
+is on ansible, each provided template installs a SSH server and the ansible packages. 
+
+The example below shows how to run a playbook using a special packer template.
+The [ansible-roles](http://git.openslx.org/openslx-ng/ansible-roles.git/) submodule
+provides ansible roles and a sample playbook, to buildthe stage3 initramfs using
+[systemd-init](http://git.openslx.org/openslx-ng/systemd-init.git/).
+Refer to those repos for more information.
+
+#### Example
+Build a stage3 initramfs with dracut inside a previously created image using the
+'run-playbook-only' packer template used to only run the 'build-dracut-initramfs'
+playbook on a previously generated image
+(e.g. output-qemu-ubuntu-16.04-amd64/ubuntu-16.04-amd64):
+```shell
+packer build -var-file=base.json \
+	-var='image_dir="output-qemu-ubuntu-16.04-amd64"' \
+	-var='image_name="ubuntu-16.04-amd64"' \
+	-var='playbook="build-dracut-initramfs.yml"' \
+	ansible-roles/run-playbook-only.json
+```
+The packer artifact is created in 'output-<image_dir>'. This artifact
+contains all the development packages needed to build the initramfs, which
+can be discarded. Instead, the base image can be used as the main stage4 image.
 
-The [ansible-roles](http://git.openslx.org/openslx-ng/ansible-roles.git/)
-repository provides ansible roles and a sample playbook, to build the stage3
-initramfs using [systemd-init](http://git.openslx.org/openslx-ng/systemd-init.git/).
-Refer to those repos for more information. The simpliest way to initialize
-the submodule is by cloning this repository with '--recursive'.
+## Notes
 
-Build initramfs inside a previously created image:
+Variables set in base.json can be overriden using packer's '-var' options, e.g.:
 ```shell
-	packer build -var-file=base.json \
-		-var='image_path='"$(jq -r '.builds[0].files[0].name' < manifest.json)"'' \
-		ansible-roles/run-playbook-only.json
+packer build -var-file=base.json -var='headless=true' <template>
 ```
-(This expects 'manifest.json' to contain only one packer artifact.)
+Make sure you first include base.json before overriding a variable or it will not work.
 
-The path to the existing image is extracted using the jq tool and given as
-'image_path' to the packer provisioning template run-playbook-only.json.
-A successful build would provide the stage3 initramfs and the VM's kernel
-in the ansible-roles/boot_files/ directory. Refer to systemd-init for more
-information on how to setup a boot environment.
-
-The packer artifact is created in 'output-<timestamp>'. This artifact
-contains all the development packages needed to build the initramfs, which
-can be discarded. Instead, the base image can be used as the main boot image.
+Partitioning the virtual disk is done during the kickstart/preseed installation. 
+A simple partition scheme is currently used: a dedicated boot partition and a
+main system partition labeled as SLX_SYS, using ext4 as filesystem. Other 
+filesystems are also supported, tested were currently xfs and btrfs. If you
+change the filesystem to use you need to adapt your boot configuration file 
+(SLX_MOUNT_ROOT_OPTIONS).
 
+Generated qcow2 image can be further compressed using libvirt tools:
+```shell
+virt-sparsify --compress <qcow2_file> <output_qcow2_file>
+```
 ## Makefile
 
 A simple Makefile to build packer templates is provided for convenience.
-See a list of targets with `make list`.
+Refer to `make help` for further instructions.
 
-Example - Build CentOS 7.3 with qemu:
+#### Example
+Build Ubuntu 16.04 LTS with qemu:
 ```shell
-	make qemu/centos-7.3-x86_64
+make ubuntu-16.04-amd64/base
 ```
-
-## Notes
-
-Variables set in base.json can be overriden using packer's '-var' options, e.g.:
+Generate boot files:
 ```shell
-	packer build -var-file=base.json -var='headless=true' <template>
+make ubuntu-16.04-amd64/base/boot
 ```
-Make sure you first include base.json before overriding a variable!
+This generates the virtual disk image under 'ubuntu-16.04-amd64/base/image'
+and the boot files under 'ubuntu-16.04-amd64/base/boot/'.
 
-The partitioning of the virtual disk is done via kickstart/preseed files. Currently,
-a simple partition scheme is used: separate boot partition, rest a the main system
-partition labeled as SLX_SYS, using ext4 as filesystem. Other filesystems are also
-supported, tested were currently xfs and btrfs. If you change the filesystem to use
-you need to adapt your boot configuration file (SLX_MOUNT_ROOT_OPTIONS).
+Only the qemu builder is currently fully supported, which is why it is
+always used if detected on the system. Virtualbox and Vmware can be used
+to build base images only, provisioning is not yet supported using these.
+Note they generate OVF and VMDK files respectively. Using qemu is
+currently recommended.
 
-While the qemu builder produces a qcow2 image, it can be further compressed using:
+## TL;DR
+0) Clone repo:
 ```shell
-	virt-sparsify --compress <qcow2_file> <output_qcow2_file>
+git clone --recursive git://git.openslx.org/openslx-ng/packer-templates
+```
+1) Build base image:
+```shell
+make ubuntu-16.04-amd64/base
+```
+2) Build initramfs for base image:
+```shell
+make ubuntu-16.04-amd64/base/boot
 ```
 
-## TL;DR
-0) git clone --recursive git://git.openslx.org/openslx-ng/packer-templates
-	or if already cloned
-0) git submodule init && git submodule update
-
-1) Build base:
-	packer build -var-file=base.json -only=qemu ubuntu-16.04-amd64.json
-
-2) Build initramfs:
-	packer build -var-file=base.json -only=qemu -var='image_path='"$(jq -r '.builds[0].files[0].name' < manifest.json)"'' ansible-roles/run-playbook-only.json
-
+## Results
 Produces:
-	- kernel & initramfs in ansible-roles/boot_files/
-	- main qcow2 image under output-ubuntu.../packer-ubuntu-amd64
+* kernel & initramfs in ubuntu-16.04-amd64/base-boot/
+* main qcow2 image under ubuntu-16.04-amd64/base
 
 To boot:
-	- qocw2 image -> dnbd3 server
-	- kernel, initramfs and config pointing to the above image on http server
+* deploy qcow2 image on your dnbd3 server
+* deploy kernel and initramfs on http server
+* point to the new dnbd3 image in your config file, see template:
+    *   http://git.openslx.org/openslx-ng/systemd-init.git/tree/dev-tools/example-openslx.config
-- 
cgit v1.2.3-55-g7522