Basic readme

Readme.md

@@ -0,0 +1,57 @@
+## Overview
+
+`hugo/images` is a portable, self contained system for distributing
+disk images.
+It allows to boot connected computers over the network and run a image distribution software on them.
+
+## Usage
+
+### Network setup
+
+This system is meant to be used in physically separated network, with all the computers (including the server) connected to a switch. The server will run DHCP server itself.
+
+### Building
+
+To build, just build the docker container from the `Dockerfile`, for example:
+
+```docker build . -t hugo/images```
+
+When run for the first time, the build might take some time because basic Debian image has to be downloaded. On subsequent builds the cache will be used making the build take much less time.
+
+### Running
+
+This container has some requirements to work properly:
+
+- `INTERFACE` environment variable should be set to an interface on which you want the server to operate. You can do this by appending `-e INETRFACE=whatever` to your `docker run` command.
+
+- The server has to be run in privileged mode, so `--privileged` flag has to be added to the command.
+
+- No network isolation of any kind should be enabled. You can connect the container directly to host's interface with `--net host` flag.
+
+An example run command might look like this:
+
+```docker run -e INETRFACE=eth42 --privileged --net host hugo/images```
+
+After starting the server, all PCs connected to the network, when in network boot mode, should boot linux for cloning and present the user with a menu.
+
+## Technical details
+
+The container runs three services: DHCP server, TFTP server and HTTP server (on port 8014, to avoid collisions with HTTP server that can be already running on host system). DHCP server is used to assign IP addresses and point to PXE binary which will continue the boot process, TFTP server is used, as specified in PXE standard, to send basic files needed to boot, and HTTP, as it is much faster than TFTP, is used to transfer whole root filesystem.
+
+### Boot process
+
+The boot process of a computer connected to the server
+
+1. The computer searches for DHCP server and asks for an IP address. The server responds  (as configured in `src/dhcpd.conf`) with an IP address and the filename of PXE binary.
+
+2. The PXE binary is downloaded over TFTP. When run, it searches (by trying many names, including `pxelinux.cfg/default`) for PXE config file and downloads it over TFTP.
+
+3. This config file (`src/pxelinux.cfg/default`) contains filenames of the linux kernel and initial ramdisk, which are downloaded over TFTP.
+
+4. A network is configured in initrd and full filesystem (as squashfs) is downloaded over HTTP (port 8014) and mounted read-only as `/dev/loop0`. See `linux/src/initramfs-tools/scripts/local-top/download.sh` for more details.
+
+5. As specified in `linux/src/etc/fstab`, a `tmpfs` is mounted in `/tmp`.
+
+6. `root` is automatically logged in and it's default shell, the image distribution software (see `linux/scripts`), is started.
+
+### Linux