update bank docu and code to make it work

1 files changed, 53 insertions, 44 deletions

diff --git a/INSTALL b/INSTALL
index 939710c..30dbe7a 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,23 +1,39 @@
-================== HOW RUN THE PYTHON BANK =====================
+================== HOW INSTALL THE PYTHON BANK =================
 
 ----------------------------0 Preface --------------------------
 
-In order to get the whole bank's codebase, a submodule needs to be
-pulled; so from the bank's top directory, run
+In order to get the complete bank's codebase, a submodule needs to be
+pulled. To do this, run:
 
 $ git submodule update --init
 
-(this submodule carries some HTML/JS code which is reused among all
-Taler's Web components)
+(This submodule carries some HTML/JS code which is reused among all
+Taler's Web components.)
 
 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. In order to achieve that, run
+the bank. To grant access to Postgres 9.x, run:
 
 $ su # give root password
-$ su - postgres # no password should be given here
-$ psql -c "create database talertest owner OWNER" # where OWNER \
-is the user who will run the bank
+# su - postgres
+$ createuser -d $TALER_BANK_USER
+
+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 ------------------------
 
@@ -72,22 +88,8 @@ $ 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 ----------------------------
-
-NOTE
-
-(*) 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 final "executable" (i.e. a shell script which launches the wsgi service),
-so it should be somewhere known by PATH
 
-(*) 'make install' performs both sources deployment _and_ database initialization;
-the latter needs to be done with the same user who runs the bank application. So if
-'make install' is done as 'root' user, make sure 'root' has the mean to modify the
-'talertest' database. Otherwise, just point '--prefix' and '--exec-prefix' to a location
-accessible to the user who will run the bank
+--------------------- 2 The GNU way ----------------------------
 
 The installation is done by the usual
 
@@ -96,46 +98,53 @@ $ ./configure
 $ make
 $ make install
 
-At this point a DB-less bank should be installed. In order to operate with it,
-the following three steps must be matched (*):
+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:
 
-1) a DB called 'talertest' must exist, with the user running the bank having
+0) a DB called 'talertest' must exist, with the user running the bank
 owning it; try:
 
-$ taler-bank-manage --createdb OWNER # OWNER will own this DB
+$ taler-bank-manage --createdb
 
-In case of failure, see the Preface above
+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.
 
-2) some canonical tables must be defined on 'talertest'
+1) Some canonical tables must be defined on 'talertest':
 
-$ taler-bank-manage --defintables
+$ taler-bank-manage --definetables
 
-3) some predefined accounts must be created
+2) Some predefined accounts must be created:
 
 $ taler-bank-manage --preaccounts
 
-4) Optional, to populate the DB with sample data, issue
+3) To populate the DB with sample data, OPTIONALLY issue:
 
 $ taler-bank-manage --sampledata
 
-(*) Steps 2-4 are embedded in the single command
+4a) To quickly run the bank as an HTTP server without nginx and
+without the SSI, run:
 
-$ taler-bank-manage --all
-
-If in doubt, issue
-
-$ taler-bank-manage --help
+$ taler-bank-manage --barebank
 
-If the previous steps were successful, then the bank should be run with
+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 includes.
+SSI and the above runs the WSGI protocol, not HTTP!  This is described
+in the next section.
 
-To quickly run the bank without nginx, do
-
-$ taler-bank-manage --barebank
 
 ----------------- 3 How to bind Django and nginx ---------------