Improve the README for consumers.

README.md

@@ -1,18 +1,20 @@
 minideb
 =======
 
-A small container image with apt available.
+A small base image designed for use in containers. The image
+is based on glibc for wide compatibility, and has apt for
+access to a large number of packages. The image is based
+on Debian, with some things that aren't required in containers
+removed:
 
-We want to have the smallest container image possible with
-apt available. Small images are great, but the power of
-apt is hard to live without.
+  * Some packages that aren't often used in containers
+    (hardware related, init systems etc.)
+  * Some files that aren't usually required (docs, man pages,
+    locales, caches)
 
-These images are Debian-based, but they are not Debian, as
-they remove some `Essential` packages that are not needed in
-most containers (e.g. init). This does mean that while apt
-is available, with the whole Debian archive, some packages
-will not work correctly without also installing a missing
-`Essential` package.
+This image aims to strike a good balance between having
+small images, and having many quality packages available
+for easy integration.
 
 These images also include an `install_packages` command
 that you can use instead of apt. This does two things:
@@ -20,9 +22,46 @@ that you can use instead of apt. This does two things:
   1. Install the named packages, skipping prompts etc.
   2. Clean up the apt metadata afterwards to keep the image small.
 
+e.g.
+
+    $ install_packages apache2 memcached
+
+Compatibility
+-------------
+
+The image points to the Debian archive, so you are free to
+install packages from there that you need. However because
+some `Essential` packages have been removed they may not
+always install or work correctly.
+
+In those cases you can figure out which package is needed
+and manually specify to install it along with your desired
+packages.
+
+Docker
+------
+
+You can use the image directly, e.g.
+
+    $ docker run --rm -it minideb:latest
+
+There are tags for the different Debian releases.
+
+    $ docker run --rm -it minideb:jessie
+
+The images are built daily and have the security release enabled,
+so will contain any security updates released more than 24 hours
+ago.
+
+You can also use the images as a base for your own `Dockerfile`:
+
+    FROM minideb:jessie
+
 Building
 --------
 
+You can build an image yourself if you wish:
+
 - Install debootstrap and debian-archive-keyring.
 - sudo ./buildall
 
@@ -34,25 +73,3 @@ To test the resulting image:
 
 - docker import -t minideb:jessie jessie.tar
 - ./test minideb:jessie
-
-Nami
-----
-
-Nami from Bitnami allows you to install Bitnami-maintained packages.
-
-The `namibase` directory contains `Dockerfile`s for building images
-containing `nami` based on the minideb images. They will also be build
-by the `buildall` script. You will first have to download the
-`nami-linux-x64.tar.gz` tarball in to the `namibase` directory, but
-unfortunately there is no public source for those tarballs currently.
-
-TODO
-----
-
-  - Look at whether the process produces the same bits given the same inputs
-    - It does not. `/etc/shadow` and `/etc/group` change, as well as `/var/cache/ldconfig/aux-cache`.
-  - Can we use a custom debootstrap script to avoid removing packages?
-    - Yes, and allows to define a package set to include, rather than a list of packages to remove.
-    - Requires to install some packages (e.g. mount) for running the process, that we would still
-      want to remove afterwards.
-  - `install_packages` to also run the docs/locales/etc. cleanups