New Readme

Announced long ago, finally here we are : a new README!

README

-This is lipck - the "linux install party customization kit".
-
-This package of scripts is intended for remastering Ubuntu based 
-distributions.
-This collection of scripts was created by members of the
-Open-Source working group of the Fachschaft 1/1 Mathematik, Physik,
-Informatik of the RWTH Aachen University for remastering images for their
-Linux Install Parties.
-Existing solutions such as UCK could not do some things we wanted to do like 
-updating the initramfs kernel, saving space by deduplicating files between
-multiple architectures (e.g. x86,x64). We release this collection of scripts
-in hope that they will be useful for someone else as well.
-
-This project is licensed under the terms of the GPLv3 license which you can
-find in the COPYING file.
+Linux Install Party Customization Kit (lipck)
+=============================================
+
+Content
+-------
+
+0. License
+1. About
+2. Requirements
+3. HowTo
+4. Tips
+
+License
+-------
+
+lipck is licensed under the GPLv3. See the COPYING file for further
+details.
+
+
+About
+-----
+
+lipck is a helper tool for remastering Ubuntu based distributions. Amongst
+others it can
+- apply patches to rootfs/isofs/initramfs,
+- update the initramfs kernel,
+- preinstall packages into the rootfs,
+- provide a custom package archive on the install media; this allows a user
+  to install extra packages without internet access,
+- merge i386 and amd64 install media (including file deduplication and
+  automated architecture recognition in grub),
+- autogenerate grub configuration from templates.
+
+In comparison to other tools, like UCK, the host system is independent of the
+system remastered. Furthermore, the host is kept clean with respect to resources
+(like mount points). This is achieved by using linux namespaces/lxc.
+
+However, in its current state each version of lipck (git tag/commit) is designed
+for a specific Ubuntu version. While the version/source image can be configured
+freely, patches and static files (i.e. those in the contrib directory) are
+not versionized and do only apply to a single Ubuntu image.
+
+Originally, lipck was (or still is) created to remaster install images for
+linux install fests organized by members of the Open Source Arbeitskreis of
+the Fachschaft 1/1 Mathematik, Physik, Informatik of the RWTH Aachen University.
+It is published in hope that it will be useful for someone else as well.
+
+
+Requirements
+------------
+
+lipck makes use of the following tools (make sure they are installed):
+
+- 7z
+- bzip2
+- cpio
+- diff
+- git
+- (GNU) ddrescue
+- (GNU) make
+- grub (i386-pc, i386-efi, x86_64-efi)
+- lxc
+- patch
+- rsync
+- squashfs-tools (mksquashfs, unsquashfs)
+- tar
+- util-linux
+- wget
+- xz/lzma
+
+And, optionally,
+
+- VirtualBox tools (vboxmanage) to create a vmdk image.
+
+HowTo
+-----
+
+In short: run
+	$ make WORKSPACE=/media/drivewithspace config
+	# make image
+	# make repo  #build offline repository (optionally)
+	# make IMAGE_FILE=/somewhere/myfinalimage.img image_deploy
+	# make IMAGE_FILE=/somewhere/myfinalimage.img image_deploy_vmdk
+
+where the first command should be executed as user (the owner of the lipck git)
+and all others as root. /media/drivewhitspace should provide enough disk space
+to store the basic isos, the extracted rootfs/initramfs, etc. (~40G should
+suffice). image_deploy will assemble the final (raw) image. The last command
+is optional again (note that IMAGE_FILE should have the same value as in the
+previous line).
+
+In practise, you may want to edit some configuration files/patches prior to
+invoking make as described above:
+
+- the most important config file is config/Makefile.conf where, among others,
+  the base iso can be configured. See config/examples for more details.
+
+- contrib/rootfs/{hold_packages,pre_installed_packages*} lets you control the
+  packages that will be installed preinstalled in the rootfs.
+
+- contrib/rootfs/offline_repo.json defines all packages available in the
+  offline repository.
+
+- Files in contrib/rootfs/{modprobe.d,skel,sysctl.d} will be copied as is
+  to the corresponding folders in the rootfs.
+
+- patches/{initrd,iso,rootfs} contains patches for the initramfs,
+  iso/images root, and the rootfs. Probably they have to be adapted for
+  new iso base images. Unfortunaly, version/iso specific patches are not
+  supported yet.
+
+Lastly, you may want to spawn a shell in the rootfs being remastered with
+
+	# make rootfs_console
+
+to debug stuff.
+
+
+Tips
+-----
+
+- If the rootfs_remaster target failed, it may the neccessary to execute the
+  next make command two times (the first time a dirty state will be discovered
+  and fixed).
+
+- code executed in the rootfs is located in scripts/, you may need to execute
+
+	# make rootfs_finalize
+
+  to trigger a reload of this code.
+
+
+Happy hacking!