From 661f01b13d28c3a03ba4c86fb5aa0228836d9fca Mon Sep 17 00:00:00 2001
From: Jonathan Bauer
Date: Thu, 30 Mar 2017 17:11:21 +0200
Subject: updated readme

---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 50a5c95..1a03963 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Packer-based generation of reference systems using distro's ISOs.
 Packer => 0.12.2
 Download: https://www.packer.io/downloads.html
 
-## Usage
+## Usage: Creating base images
 
 The file 'base.json' contains default variables (VM, SSH) common to all templates.
 Thus it should always be included using packer's '-var-file' option.
@@ -22,13 +22,53 @@ Debug:
 	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 produce a disk image under:
+	output-<distro>-<builder>-<timestamp>/packer-<distro>
+
+Example:
+  output-ubuntu-qemu-1490876841/packer-ubuntu-amd64
+
+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.
+
+## 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 [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'.
+
+Build initramfs inside a previously created image:
+	packer build -var-file=base.json \
+		-var='image_path='"$(jq -r '.builds[0].files[0].name' < manifest.json)"'' \
+		ansible-roles/run-playbook-only.json
+
+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 as output-<timestamp>. This provisioned image
+contains all the development packages needed to build the initramfs, which
+can be discarded.
+
 ## Notes
 
 Variables set in base.json can be overriden using packer's '-var' options, e.g.:
 	packer build -var-file=base.json -var='headless=true' <template>
 (Make sure you first include base.json before overriding a variable!)
 
-Packer connects to the VM per SSH to provision them after the initial iso installation.
+Packer connects to the VM per SSH to provision them after the initial ISO installation.
 A default password is defined in base.json and the corresponding SHA-512 hashes are set
 in the kickstart/preseed files. If you change the 'ssh_password' make sure to change the
 hashes in the ks/ps files (generate with 'mkpasswd -m sha-512')!
-- 
cgit v1.2.3-55-g7522