From 9319fec6f874c37f4a55367dc8fa2bca6dbd7af6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Motiejus=20Jak=C5=A1tys?= <motiejus@jakstys.lt>
Date: Mon, 24 May 2021 00:11:58 +0300
Subject: [PATCH] update readme

---
 README.md | 41 ++++++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index d51c959..f5f7387 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,37 @@
 Undocker
 --------
 
-Convert a Docker image to a root file system.
+Converts a Docker image (a bunch of layers) to a flattened "rootfs" tarball.
 
 Why?
----
+----
 
 Docker images seems to be the lingua franca of distributing application
-containers. It's hell convenient. But is it the best runtime environment? Not
-for everyone.
+containers. These are very wide-spread. However, is Docker the best runtime
+environment? Not for everyone.
 
-Undocker bridges the gap between image configurations and container runtimes:
-now you can run a Docker image with systemd-nspawn and/or lxc.
+Undocker bridges the gap between application images (in docker image format)
+and container runtimes: now you can run a Docker image with systemd-nspawn
+and/or lxc, without doing the `docker pull; docker start; docker export` dance.
 
 Usage -- extract docker image
 -----------------------------
 
 Download `nginx` docker image from docker hub and convert it to a rootfs:
+
 ```
 skopeo copy docker://docker.io/nginx:latest docker-archive:nginx.tar
 undocker rootfs nginx.tar - | tar -xv
 ```
 
+(the same can be done with `docker pull` and `docker save`)
+
 Usage -- systemd-nspawn example
 -------------------------------
 
+Once the image is converted to a root file-system, it can be started using
+classic utilities which expect a rootfs:
+
 ```
 systemd-nspawn -D $PWD nginx -g 'daemon off;'
 ```
@@ -32,7 +39,7 @@ systemd-nspawn -D $PWD nginx -g 'daemon off;'
 Usage -- lxc example
 --------------------
 
-Converting and creating the archive:
+Preparing the image for use with lxc:
 
 ```
 undocker rootfs nginx.tar - | xz -T0 > nginx.tar.xz
@@ -40,7 +47,7 @@ undocker lxcconfig nginx.tar config
 tar -cJf meta.tar.xz config
 ```
 
-Importing it to lxc and running it:
+Import it to lxc and run it:
 
 ```
 lxc-create -n bb -t local -- -m meta.tar.xz -f nginx.tar.xz
@@ -51,13 +58,17 @@ lxc-start -F -n bb -s lxc.net.0.type=none -- /docker-entrypoint.sh nginx -g "dae
 Note: automatic entrypoint does not work well with parameters with spaces; not
 sure what lxc expects here to make it work.
 
+About the implementation
+------------------------
+
+Extracting docker image layers may be harder than you have thought. See
+`rootfs/doc.go` for more details.
+
+The rootfs code is dependency-free (it uses Go's stdlib alone). The existing
+project dependencies are convenience-only.
+
 Contributions
 -------------
 
-These are the contributions I will accept:
-
-- pull requests for code.
-- documentation updates.
-
-I am very unlikely to react to bug reports (even if they are legit) without
-accopmanying pull requests.
+I will accept pull request for code (including tests) and documentation. I am
+unlikely to react to bug reports without a patch.