merge old README and old installation instructions

1 files changed, 156 insertions, 17 deletions

diff --git a/README b/README
index af8f139..287b283 100644
--- a/README
+++ b/README
@@ -1,25 +1,164 @@
-TALER BANK
+This code implements a bank Web portal that tightly integrates with
+the Taler payment system.  The bank it primarily meant be used as part
+of a demonstrator for the Taler system.
 
-1. INTRODUCTION
+================== HOW INSTALL THE PYTHON BANK =================
 
-It implements a bank Web portal tightly integrated with Taler.
-This integration lies in the communication bank-wallet and bank-exchange
+----------------------------0 Preface --------------------------
 
-2. INNOVATIVE ASPECTS
+In order to get the complete bank's codebase, a submodule needs to be
+pulled. To do this, run:
 
-The user is no longer required to manually fill a wiretransfer form (when
-interacting with Taler), as that is done by the cooperation bank-wallet
+$ git submodule update --init
 
-3. PLANNING/PERSPECTIVES
+(This submodule carries some HTML/JS code which is reused among all
+Taler's Web components.)
 
-This bank is meant to remain a demonstrator for the Taler system, so
-it will evolve in parallel with other components. As of now, it is not
-supposed to become a production bank.
+As for the database backend, the bank uses PostgreSQL and needs a
+database called 'talertest' in it, owned by the user which launches
+the bank. To grant access to Postgres 9.x, run:
 
-4. DEPENDENCIES
+$ su # give root password
+# su - postgres
+$ createuser -d $TALER_BANK_USER
 
-Django
-validictory
-django-simple-math-captcha
-requests
-Python
+where $TALER_BANK_USER is the username of the user who will run the
+bank.
+
+For Postgres 8.x, the last step needs to be changed to just:
+
+$ createuser
+
+then enter the username interactively. When asked, do not set it to
+superuser, but allow the creation of databases, and do not allow the
+creation of new roles.
+
+
+After this, you can follow two styles of installation, the Pythonic
+way or the GNU way.  The Pythonic way is recommended for development,
+while the GNU way is recommended for actual deployment.
+
+
+---------------------1 The Pythonic way ------------------------
+
+Make sure your system has 'virtualenv' and 'pip' installed.
+For example, on Debian systems, run:
+
+# apt-get install virtualenv python3-pip python3.4-dev
+
+Next, create an environment which will "host" the bank's dependencies:
+
+$ virtualenv bank_env
+
+This should create a directory named 'bank_env/' in your current
+working directory.
+That directory will contain all the Pythonic dependencies of the bank.
+
+To activate your environment in the current shell, use:
+
+$ source bank_env/bin/activate
+
+(To later deactivate it, you can simply close the shell.)
+Inside the "activated" shell, install the dependencies:
+
+$ pip install -r requirements.txt
+
+The file 'requirements.txt' is contained in this folder.
+
+Once the environment is set up, the bank can be launched. For that
+purpose, you need to first
+
+$ cd django/
+
+Before actually launching the bank, the bank's database and static files'
+serving must be initialized. Give the following commands (respecting the
+sequence):
+
+$ python manage.py makemigrations
+$ python manage.py migrate $ python manage.py collectstatic --noinput
+
+The following command is also needed, in order to create some predefined
+accounts:
+
+$ python manage.py pre_accounts
+
+In order to add sample donations to predefined account:
+
+$ python manage.py sample_donations
+
+If everything has worked fine, launch the bank's web server with:
+
+$ python manage.py runserver 127.0.0.1:8080
+
+The bank's homepage is now available at http://127.0.0.1:8080
+
+
+--------------------- 2 The GNU way ----------------------------
+
+The installation is done by the usual
+
+$ ./bootstrap.sh
+$ ./configure
+$ make
+$ make install
+
+sequence. Note that you cannot skip 'make'.  For './configure',
+you can pass a few options:
+
+(*) The '--prefix' option will point a directory which hosts both the
+virtualenv data and the bank's website itself.
+
+(*) The '--exec-prefix' option will point to a directory which will
+host the executables (i.e. a shell scripts which launch the Web
+services), so it should probably be somewhere within $PATH.
+
+
+To complete the setup, you need to initialize the database:
+
+0) a DB called 'talertest' must exist, with the user running the bank
+owning it; try:
+
+$ taler-bank-manage --createdb
+
+It should either report that the database 'talertest' exists, or
+create it.  If neither works, please re-read the preface on top
+of this file.
+
+1) After the database has been created, some tables must be created:
+
+$ taler-bank-manage --definetables
+
+2) Optionally, if the bank is to be used in the demo setup, we
+   predefine certain public accounts:
+
+$ taler-bank-manage --preaccounts
+
+3) Optionally, to populate the DB with sample transaction data (i.e.
+   to check how some pages are rendered once data is present), issue:
+
+$ taler-bank-manage --sampledata
+
+4a) To quickly run the bank as an HTTP server without nginx and
+without the SSI on port 8080, run:
+
+$ taler-bank-manage --bareserver 8080
+
+4b) In production, the bank should be run with:
+
+$ taler-bank-wsgi
+
+Please note that the bank works properly only via nginx since it uses
+SSI and the above runs the WSGI protocol, not HTTP!  This is described
+in the next section.
+
+
+----------------- 3 How to bind Django and nginx ---------------
+
+The basic statements needed to run the bank via nginx are shown in
+'django_nginx.conf'. Once those statements have been applied, assuming
+your CWD is still 'django/', the bank is run with
+
+$ ./django_wsgi.sh /path/to/bank_env
+
+The nginx configuration is based on the guide in [1]
+[1] http://uwsgi-docs.readthedocs.org/en/latest/tutorials/Django_and_nginx.html