adding some basic documentation

diff --git a/README.adoc b/README.adoc
new file mode 100644 (file)
index 0000000..f0e6f44
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,49 @@
+= rescue-boot
+
+This project holds scripts that prepares a "rescue" boot image file
+with a Devuan ceres minbase filesystem.
+
+* +./minbase-strap.sh+ prepares boot-ceres-$ARCH.img
+
+  - +./minbase-strap-bios.sh+ include fragment preparing bios boot equipment
+
+  - +./minbase-strap-uefi.sh+ include fragment preparing uefi boot equipment
+
+  - +./minbase-strap-mkimg.sh+ include fragment packaging into disk file
+
+* +./run.sh boot-ceres-$ARCH.img+ boots it up in a virtual machine.
+
+== About the boot image preparation
+
+The rescue boot image is a full disk image with two partitions. The
+first is a FAT partition that contains a linux kernel and initrd for
+the kernel and boot equipments using syslinux for both legacy bios and
+UEFI bios boot.
+
+The initrd.gz file is quite large makign the partition somewhat larger
+than 100M and this makes it less ameniable as boot image for a hybrid
+ISO (which has a 32M limit).
+
+The preparation populates a root filesystem in the FS directory by
+using debootstrap followed by certain "Captain's Picks" to include
+partcular choice software.
+
+The scripting asks firstly for a kernel choice and then an init script
+choice to optionally replace the "standard" initrd init script with
+some rescue variant.
+
+== About the virtual machine setup
+
+The run.sh script starts a QEMU system emulator for the boot image
+given on the command line. E.g.,
+
+    $ ./run.sh boot-ceres-amd64.img
+
+With environment setting EFI=yes, the emulation uses UEFI boot. E.g.
+
+    $ EFI=yes ./run.sh boot-ceres-amd64.img
+
+The script assumes the host has a "vde2" setup with a "vde-switch"
+using control directory "/run/vde.ctl". Any alternatie network setup
+needs script hands-on to change the "NET=.." variable.
+