Merge branch 'master' of github.com:chbrandt/dockeri

README.md

@@ -1,28 +1,90 @@
-# DockerI
+# Dockeri
 
-My use case for Docker is of a packaging system, where stable versions of
-everyday tools I develop and/or use will be encapsulated.
+Use `dockei` to **run** docker containers with a simplified call.
+When using frequently containers, with always the same --and long--
+'`docker run`' command line, starts to get boring all that typing.
+That's why I wrote `dockeri`.
+Dockeri uses configuration files to hide unnecessary complexity of
+everyday Docker (run) calls, as well as **X11** support.
+
+My use case for Docker is of a packaging system for (astronomical)
+tools I use daily between Linux and MacOS systems.
 Some of these tools will make use of network with a browser/html interface,
 some will use X11 system and most of them will accept/return data files.
 
-When we start using docker features/options the command line becomes somewhat
-ugly and, for daily/frequently used software, it starts to be painful.
-
 This interface has two purposes:
 * to save images' common options in a config file
 * to deal with graphical (X11) interface access in Linux and Mac
 
+
 ## Install
 
-To use this interface -- `dockeri` -- we need Python-2.
-And if you're running from a MacOS, XQuartz needs to be installed
-if you plan to run graphical tools.
+> MacOSX users must have [XQuartz](https://www.xquartz.org/) installed if willing to export X11 interfaces from containers
 
-With that in place, all you have to do to run `dockeri` from anywhere in your
-system is to update your environment variable `$PATH`:
+`dockeri` is implemented in Python. Runs in Python 2 and 3, and
+does *not* depend on external libraries; only Python's standard library.
+
+To install, download the last [release](https://github.com/chbrandt/dockeri/releases)
+and do:
+```bash
+$ python setup.py install
+```
+or
+```bash
+$ pip install .
+```
+
+
+## How to use:
+
+After installing it, `dockeri` is available from anywhere in the system.
+
+Simply type `dockeri` to gets is short *usage* signature:
+```
+$ dockeri
 
+usage: dockeri [-h] [-w IO_DIR] [--nox] [-d] [-n] [-l] image
 ```
- export PATH="${PATH}:${DOCKERIDIR}/bin"
+
+If you want to run the official `ubuntu` image, type:
+```
+$ dockeri ubuntu
+```
+
+`dockeri` has also a *help* option to explain you better the available options:
+```
+$ dockeri --help
+
+usage: dockeri [-h] [-w IO_DIR] [--nox] [-d] [-n] [-l]
+
+Interface for Docker containers.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -w IO_DIR, --io IO_DIR
+                        directory to use for files exchange with container
+                        (inside container it is '/work'.
+  --nox                 do *not* export graphical interface (x11) from the
+                        container to host (*do* export by deafult)
+  -d                    runs non-interactively (detached mode)
+  -n, --dry-run         don't run the container, just print the command-line
+                        instead
+  -l, --list            print list of preset images
+```
+
+For instance, Dockeri comes with a list of preset images in the default
+configuration files.
+To see what in the list, type:
+```bash
+$ dockeri --list
+List of available/preset images:
+- annz
+- dachs
+- ds9
+- gollum
+- heasoft
+- jupyter
+- topcat
 ```
 
-[]
+/.\