INSTALL

   1 This file contains instructions for installing a Trubanc server and client.
   2
   3 1) Get the contents of http://trubanc.com/trubanc.tar.gz into your web
   4    service directory. Or get it with git:
   5
   6    git clone git://github.com/billstclair/trubanc.git trubanc
   7
   8 2) Copy settings.php.tmpl to settings.php, and edit it for your environment
   9
  10 3) To modify the home page, create a new home page HTML file (NOT
  11    index.html), and set the $index_file value in settings.php to
  12    its name. This file must be plain HTML. PHP will not be
  13    interpreted.
  14
  15 4) Copy client/settings.php.tmpl to client/settings.php, and edit it.
  16
  17 5) Aim your web browser at bankinit.php under your Trubanc URL to
  18    create client accounts for the bank and an administrator. For
  19    example, if your Trubanc server is at http://example.com/, aim your
  20    browser at:
  21
  22    http://example.com/bankinit.php
  23
  24    Follow the instructions there. Make sure to pick good passphrases,
  25    so that it's unlikely that anyone can break in.
  26
  27 6) To modify the appearance of the client web page, copy
  28    client/template.php into a new php file in the same directory,
  29    change it, preserving the functionality of the variables documented
  30    at the top of the file, and set $template_file in
  31    client/settings.php to its name.
  32
  33 Notes
  34 =====
  35
  36 Step 5 above initializes the server and client databases, adds the
  37 server to the client database, with a passphrase you select, and
  38 creates an adminiatrator account with 10,000 usage tokens initially
  39 spent from the bank.
  40
  41 I recommend that you use the bank's account only to spend usage tokens
  42 to the administrator account. Use the administrator account to create
  43 new user coupons and to conduct other bank business. Also use the
  44 administrator account to issue any bank-owned assets.
  45
  46 $dbdir for both client and server must be writable by the web
  47 server. The directories should not be directly servable by
  48 Apache. Otherwise, people will be able to snoop on the "database", and
  49 steal your bank's PGP private key, and information about customer
  50 accounts. That would be bad.
  51
  52 If your installation doesn't allow you to have writable files anywhere
  53 BUT the web server directory, you can create an .htaccess file in the
  54 database directories, or a parent directory, containing the following,
  55 to deny access to the database files from a web browser:
  56
  57   RewriteEngine On
  58   RewriteRule .* - [F]
  59
  60 Some PHP SAFE_MODE installations will require you to set the
  61 permission on the database directories to 2777, and enable
  62 safe_mode_gid. If you see an error like the following when running
  63 bankinit.php:
  64
  65   Can't open for write: dbs/serverdb/pubkey/36a6db2903b42d35e753d44d95636490b0fb7b2c
  66
  67 then you should remove the server database directory, recreate it, and
  68 change its permissions to 2777.
  69
  70 You will probably want to use SSL (https, encrypted connection) for
  71 your client, and, until I make Trubanc support client/server
  72 encryption internally, your server. After you install your SSL
  73 certificate, and assuming your server is in the "trubanc" directory,
  74 you can create an .htaccess file at the top-level of your site,
  75 containing the following, to enable HTTPS for only the client. Remove
  76 "client/" to enable it for the client and server.
  77
  78   RewriteEngine On
  79   RewriteCond %{HTTPS} !=on
  80   RewriteRule ^trubanc/client/(.*) https://example.com/trubanc/client/$1 [R,L]
  81
  82 Or, if your server is at the top-level of your site:
  83
  84   RewriteEngine On
  85   RewriteCond %{HTTPS} !=on
  86   RewriteRule ^client/(.*) https://client/$1 [R,L]
  87
  88 If the RewriteRule doesn't work in your Apache installation, you can
  89 set the $ssl_domain variable in settings.php for client and/or
  90 server.
  91
  92   $ssl_domain = "example.com";