Add README.md (markdown).

This file could be viewed by git browser (e.g. cgit).

2 files changed, 71 insertions, 28 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..19055ae
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+## About
+vipeval is a backend service for ECS/ViP. It's running as a pure client i.e. there is no server running.
+
+* You need Ruby 2.1.x installed
+* No database needed
+
+It's allowed to run multiple instances of vipeval. They work cuncurrently
+on their ECS resources.
+
+## Installation
+Just download
+[vipeval-master.tar.gz](https://git.freeit.de/vipeval/snapshot/vipeval-master.tar.gz)
+and unpack or clone via `git clone https://git.freeit.de/vipeval`.
+
+##Configuration
+Change into `vipeval` directory. Edit `config/appcfg.yml` (see explanations
+in config file). Normally you should only edit under `ecs:`.
+
+## Running
+### Running in foreground
+Change into `vipeval` directory and type:
+
+    bundle exec rails console -e production
+
+In the upcoming irb (interactive ruby shell) type:
+
+    MainLoop.instance.start
+
+### Running in background
+For instance via rails runner, change into `vipeval` directory and type:
+
+    bundle exec rails runner -e production MainLoop.instance.start &
+
+or
+
+    /path/to/vipeval/bundle exec rails runner -e production MainLoop.instance.start &
+
+You can place this also in a startup script (e.g. [sles12 init
+script](doc/vipeval_sles12_startscript)):
+
+    ...
+    case "$1" in
+        start)
+            echo -n "Starting VIP Evaluation Backend"
+            su -l -c "cd $VIPEVAL_ROOT && bundle exec rails runner -e production MainLoop.instance.start &" freeit
+            rc_status -v
+            ;;
+        stop)
+    ...
+
+### Providing ECS basic auth credentials via environment variables
+For security reasons you may want to serve at least the ECS login password
+via shell environment variable. Therefore you must uncomment the
+`#password: <%= ENV['ECS_PASSWORD'] %>` line in `config/appcfg.yml` and
+comment the old `password: ...` line. then you can provide the password as
+an environment variable at the command line:
+
+    ECS_PASSWORD=my-secure-password bundle exec rails console -e production
+
+or
+
+    ECS_PASSWORD=my-secure-password bundle exec rails runner -e production MainLoop.instance.start &
+
+Of course it's up to you how you set the ECS\_PASSWORD enverionment
+variable. For instance you set it in your startup script (e.g. [sles12 init
+script](doc/vipeval_sles12_startscript)), which is owned by root and could
+only read by him. Or read it from a file owned and readable by root:
+
+    ECS_PASSWORD=$(cat my_password_file) bundle exec ...
+
+
diff --git a/README.rdoc b/README.rdoc
deleted file mode 100644
index dd4e97e..0000000
--- a/README.rdoc
+++ /dev/null
@@ -1,28 +0,0 @@
-== README
-
-This README would normally document whatever steps are necessary to get the
-application up and running.
-
-Things you may want to cover:
-
-* Ruby version
-
-* System dependencies
-
-* Configuration
-
-* Database creation
-
-* Database initialization
-
-* How to run the test suite
-
-* Services (job queues, cache servers, search engines, etc.)
-
-* Deployment instructions
-
-* ...
-
-
-Please feel free to use a different markup language if you do not plan to run
-<tt>rake doc:app</tt>.