=====================================
Taler @ NetzBon deployment automation
=====================================

This directory contains a set of scripts for deploying Taler by asking
questions to the user and providing the values to the various Taler subsystems
(LibEufin, Exchange, Merchant, ..) and other components (nginx, systemd).

main.sh is the entry point script for the Taler setup. It asks the questions
and puts the answers in environment variables and/or replaces them into Nginx
configuration file(s).

The main.sh script can be re-run whenever the setup process was interrupted,
for example due to problems (domain name setup, etc.) that the admin needs to
fix first.

Getting Started
===============

The setup scripts are currently only tested on Ubuntu Kinetic Kudu.

Start by cloning the deployment.sh repository:

$ git clone git://taler.net/deployment.git

Proceed with the setup by executing the main.sh script:

$ cd deployment/netzbon
$ ./main.sh

After the setup is complete, you can:
- go to https://bank.$domain/, log in as admin
  and create the first (merchant) bank account(s)
- fund one of the accounts (see section "Funding of bank accounts"),
  so that withdrawal can be tested
- log into the bank with the funded (non-admin) account, withdraw electronic
  cash via the bank UI into the Taler wallet (either browser extension wallet
  or Android wallet)
- go to the merchant backoffice (https://backend.$domain/),
  log in, configure the instance (do not forget to set an access token),
  create the first order and pay for it with the wallet.


Domain names
============

Assuming a main domain at netzbon.ch (i.e. "netzbon.ch" will be given as the
value for the domain during configuration), this setup expects the following
subdomains to be reachable:

- exchange.netzbon.ch
- bank.netzbon.ch
- backend.netzbon.ch (merchants frontends need this)


Setup guide
===========

The following recommendations apply for questions from the "main.sh" script:

- "Run taler-exchange-offline?"
  => Answer with "yes", otherwise manual offline key management
  has to be done by the sysadmin.
- TLS: yes, as long as the domain is externally reachable for letsencrypt

When packages are installed, the package manager will ask questions about the
database configuration:
- "Configure database for XZY with dbconfig-common?"
  => Should be answered with "yes"
- "Please select the remote hostname to use"
  => Select "localhost"
- "PostgreSQL application password"
  => Should be left blank, so that installer will use secure random password.


Funding of bank accounts
========================

After a successful installation, all the services are running
and the administrator can create bank accounts and wire funds
to them.  The script "transfer.sh" in this directory serves this
purpose; running it without arguments shows the usage instructions.

Note: The wiring of funds causes the amount to be subtracted from the "admin"
bank account.  Following is one example of wiring funds from the administrator
to the "shop" bank account. 

  $ ./transfer.sh shop NETZBON:10 "welcome amount"

If the command succeeded, the 'shop' bank account has received
one payment of 10 NETZBONs from 'admin' with the subject "welcome
amount".

Concept
=======

The different stages of the installation have their own shell
scripts, driven by the 'main.sh' master script. Splitting up the
process into the main stages should make it easy to resume if any
particular step fails for any reason.

The different stages communicate via environment variables which
they may consume or export for future stages.  The 'main.sh' script
prompts the user for the following inputs:

* the main domain name (subdomains may be created automatically)
* the name of the currency
* the master password to set for the administrative Web interface

The setup is fundamentally based on the Debian packages.  The scripts
should do the minimal amount necessary to get GNU Taler to work on top
of what the Debian packages provide.  If we can move logic into a Debian
package, we should.  However, the Debian packages MUST install non-interactively
[NOTE: they do for the DB config], so site-specific inputs MUST be
done by the shell scripts.

The shell scripts should be kept simple, and for example use default
configuration(s) from the Debian packages and replace values with 'sed'
instead of generating complete configurations themselves (where possible,
so in particular for the reverse HTTPS proxy configuration).


Components
==========

The goal is not to only setup the Debian packages, but to also configure
all of the components:

* libeufin-sandbox with an account for the administrator and the exchange
* libeufin-nexus with access to the exchange account and Taler facade
* exchange with denominations, fees (all zero) and credentials for the libeufin-nexus
* merchant backend with the master key of the exchange for the target currency


Future
======

For now, it is assumed that the taler-exchange-offline functionality is run
locally (in a system that is online).  Future deployments should aim at moving
the offline keys in a offline system.

For now, we do not integrate the currency conversion / cash out logic and
only have libeufin-nexus between libeufin-sandbox and exchange. In the future,
nexus will also communicate with an external bank.