From 494fa3dc32f628e0e00a3455a87309fd14af12ed Mon Sep 17 00:00:00 2001
From: Solene Rapenne <solene@perso.pw>
Date: Sun, 30 May 2021 13:25:28 +0200
Subject: [PATCH] Document the concept

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1d0cecf..57bca38 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,55 @@
-# Pocker
+# Introduction
 
-Simple chroot management
\ No newline at end of file
+`pocker` is a tool to mimic `docker` on OpenBSD using chroot.  Each step of the `Pockerfile` create a separate file hierarchy until the last instruction that will be used on the latest incremental version of the hierarchy.  Using hard links on the filesystem, it will allow grafting a local directory into the chroot for persistency.
+
+# Usage
+
+Create a `Pockerfile` with:
+
+```
+PROOT
+PKG nginx
+RUN /etc/rc.d/nginx
+```
+
+Then run using local `/var/pocker/volumes/www` in the chroot at `/var/www/htdocs/`:
+
+```
+pocker create nginx
+pocker -d /var/pocker/volumes/www/:/var/www/htdocs/ nginx
+```
+
+At the create step in `/var/pocker/chroot/nginx/` multiples directories will be created: `step1-${line1 checksum}` then a rsync from `step1-${line1 checksum}` will be done into `step2-${line2 checksum}` and so fort until the last run command creating a last environment still using rsync, allowing to easily clean the pocker enviroment upon restart.
+
+```
+ls /var/pocker/chroot/nginx/
+step1-b559bfe9f2d456b96fa836bba713169b5e9a3480e9d67bfb30afc9c38fa5f8bb
+step2-5a8ab23cdfb2240ece269ddcffe26c0750d56cb84adb054ae8bcdad51e5841e2
+run-0a5f640ed9c98aca444c675f34ef7ee57da0a07d0f20b3565595a42baf2664a4
+run -> run-0a5f640ed9c98aca444c675f34ef7ee57da0a07d0f20b3565595a42baf2664a4
+```
+
+# Pockerfile syntax
+
+- `PROOT`: create a chroot using the current system as a model using `proot` command
+- `PKG`: will run pkg_add in the chroot
+- `RUN`: command run when the pocker is started
+
+# Ideas
+
+- using hard links for each environment step for speed and disk usage efficiency
+- allow exporting / importing chroots
+
+# FAQ
+
+## Why the name pocker
+
+Because it bluffs about the environment.
+
+## Why not docker
+
+Because it's complicated and not easily reproducible on all operating systems.
+
+## Why pocker
+
+Because it allows low cost sandboxing without any special requirement.