@@ 0,0 1,113 @@
+# BEM -- Build Environment Manger
+
+A simple tool to manage build environments based on Docker.
+
+Whenever you run `bem [some command]`, it searches your current and any parent
+directories for a `BEMfile`, which is an INI file with configuration
+information. It will then build a `Dockerfile` (either in the same directory as
+`BEMfile`, or somwhere else if configured by CLI argument or the `BEMfile`),
+and execute your command within the resulting container.
+
+BEM will automatically perform user account translation, and map (i.e. bind
+mount) your "project directory" (usually the location of the `BEMfile`) into
+the Docker container at the same absolute path as on your host system. BEM will
+also carry over your environment, as well as set up X11 access.
+
+BEM is intended to make it easy to manage dependencies in a language agnostic,
+re-producible way that is accessible to non-experts (especially those who are
+unfamiliar with Docker).
+
+## Installation
+
+`python3 ./setup.py install`
+
+## Usage
+
+See `bem --help`.
+
+## Project Status
+
+BEM is currently at a **pre-alpha** level of quality, and should not be used in
+production environments.
+
+## Goals
+
+* Be easy and simple to use for users in a way that does not require them to be
+ familiar with Docker.
+* Operate on source files and build artifacts on the host filesystem, to
+ avoid extra difficulty with moving data to and from Docker containers.
+* Be fast and convenient for those who know Docker already to manage build
+ environments with.
+* Allow re-producible build environments to be used across many different
+ systems, such as developer workstations and CI.
+
+## Non-Goals
+
+BEM explicitly does not attempt to solve the following problems:
+
+* Security -- in short, you should not use BEM to run code you would not
+ otherwise run.
+ * In somewhat mode detail, BEM may mitigate certain types of attacks.
+ It's probably roughly as safe as running code in a chroot as root.
+ This is ostensibly safer than running code directly as root on the
+ host OS, but if you intend to use BEM for security-related purposes,
+ you better be very familiar with the security implications of Docker
+ containers.
+* Replace `docker-compose` -- BEM is not intended for managing long-running
+ Docker containers (i.e. containing servers), nor is it intended to
+ orchestrating multiple Docker containers together.
+* Replace Kubernetes -- BEM is not intended as a "cluster manager", nor for
+ solving resource allocation or workload distribution.
+* Replace AppImage or other distribution or runtime package solutions.
+
+## FAQ
+
+### Why Not Just Use Docker?
+
+Many developers are unfamiliar with Docker, since it is not directly relevant
+to their job or expertise. BEM seeks to enable these people to benefit from the
+positives of Docker without having to spend too much time learning new tools.
+
+Additionally, BEM acs as a set of "sane defaults" for using Docker in an
+interactive context. Think oh-my-zsh or SpaceEmacs.
+
+### Why Not Kubernetes / Docker-Compose or Another Off The Shelf Tool?
+
+None of these tools are optimized for convenient for interactive use while
+developing locally. In particular, these types of tools tend to be focused on
+running one or more long-running server processes, usually in a non-interactive
+fashion; BEM aims to do the opposite. Additionally, they (subjectively) require
+much more expertise to set up and use.
+
+### What Was the Motivation Behind BEM?
+
+First, I wanted a convenient way to keep different build environments separated
+from one another. However, I don't often write code that could be described as
+a "server" process, usually write code that runs as a monolithic process (i.e.
+not as a set of networked services), and I don't want to have to go through the
+process of `docker build`, `docker run` every single time i want to do anything
+in my build environment.
+
+Secondly, I hope to create a tool which is useful for other researches in my
+lab to help them solve the problem of dependency management. Many of these
+people are very smart, but also far too busy to learn to use a tool like
+Docker. BEM hopes to make it easier for us to collaborate on projects without
+every project member being deeply familiar with Docker.
+
+Further, BEM aims to work with existing build systems, testing processes, and
+so on. If a project already builds with `./configure ; make`, just running `bem
+./configure \; make` will allow it to build in just the same way as before,
+without requiring any effort to port over (aside from writing a Dockerfile
+describing the program's Dependencies).
+
+### Why Not LXC/`systemd-nspawn`/FreeBSD Jails/Some Other Container Manager
+
+I am not familiar with those systems. Docker is portable (relatively speaking)
+and widely used and understood. There may be other container management systems
+that could be used instead.
+
+### Isn't Running Everything Through Docker Slow?
+
+Not really. It definitely adds to start-up time, especially if the image needs
+to be rebuilt. However, starting cold from an image that has already been built
+and cached, BEM only adds 1-2 seconds of additional start up time.