Description
===========

This setup orchestrates the following containers:

1.  Banking (libEufin)
2.  Shop(s)
3.  Payment service provider (Taler exchange and helpers)
4.  Database

FIXME (#7463): the current version requires the user to manually
point the bank SPA to any backend not being served at bank.demo.taler.net.

How to compile
==============

The base image (not managed by the docker-compose setup) and
all the other images must be compiled.

Base image
----------

This image contains a minimal Debian distribution
with ALL the Taler software and its dependencies.

From this directory, run:

  $ ./build_base.sh [--help] [tags-file]

Composed containers
-------------------

From this directory, run:

  $ docker-compose build

Hotfixes
--------

Attach to the base image first: 

  # $HOTFIX is arbitrary; helps avoid copying and pasting alphanumeric IDs
  $ docker run --name $HOTFIX -it taler_local/taler_base /bin/bash

From inside the container, navigate to "/$REPO", issue
"git pull" and install the software as usual.  Exit the
container thereafter.

Commit the container having the hotfix:

  $ docker commit $HOTFIX

That outputs a new ID ($RETVAL).  That is the ID of the
modified image.  Tag it, to let other images use it to build:
  
  $ docker tag $RETVAL taler_local/taler_base:latest

Now build all the images with docker-compose, as described
in the 'How to run' section.

How to run only one image
=========================

The following commands run only one image, from those
belonging to the compose file.  Note that such image may
easily fail because it likely relies on other images not
being run.

$ docker-compose build $image-name # if also new changes need to be tested.
$ docker-compose up $image-name 

'bank', 'exchange', 'merchant', 'talerdb' are valid values
for $image-name.

Enabling tipping
================

The following command manually creates a tipping reserve:

$ taler-harness deployment tip-topup --merchant-url https://backend.demo.taler.net/instances/survey/ --merchant-apikey=$MERCHANT_APIKEY --bank-access-url https://bank.demo.taler.net/demobanks/default/access-api/ --wire-method=iban --amount=KUDOS:5000 --bank-account=survey-at-sandbox --bank-password=$SURVEY_SECRET --exchange-url https://exchange.demo.taler.net/

The status of tipping reserves can be checked via:

$ taler-harness deployment tip-status --merchant-url https://backend.demo.taler.net/instances/survey/ --merchant-apikey=$MERCHANT_APIKEY

To purge all non-funded tipping reserves, run:

$ taler-harness deployment tip-cleanup --merchant-url https://backend.demo.taler.net/instances/survey/ --merchant-apikey=$MERCHANT_APIKEY



How to run
==========

Configuration
-------------

Export the env variable TALER_SANDCASTLE_CONFIG to an
absolute path of the configuration directory.  See config/
for an example configuration directory.

Run
---

The following command starts all the services in the background,
and manages all the restarts.  Run it from this directory:

  $ docker-compose up --remove-orphans -d

The ports exposed on the host by each service can be changed
via the following environment variables:

- TALER_MERCHANT_PORT
- TALER_BLOG_PORT
- TALER_DONATIONS_PORT
- TALER_SURVEY_PORT
- TALER_LANDING_PORT
- TALER_SYNC_PORT
- LIBEUFIN_SANDBOX_PORT
- LIBEUFIN_NEXUS_PORT
- LIBEUFIN_FRONTEND_PORT
- TALER_DB_PORT

TALER_DB_PORT is not used by the contained services, but
allows a 'psql' instance to attach to the contained database
for debugging.

On a daemonized setup, live logs can still be seen by running
the following command from this directory:

  $ docker-compose logs --tail=$NUM --follow [container-name]

To stop the services, run the following command from this directory:
  $ docker-compose stop

To start the services in the foreground, run the following command
from this directory (no restart is provided):

  $ docker-compose up --remove-orphans --abort-on-container-exit

Volumes
-------

Data is kept into Docker volumes.  To export database, key
material, and logs, run the following command from this directory.

  $ ./backup.sh

The following command imports the TAR backup from
the previous step into the Docker volumes.  From this directory:

  $ ./import-backup.sh $PATH_TO_THE_TAR_FILE

The following command gives a shell to inspect the data volume:

  $ docker run -v demo_talerdata:/data -it taler_local/taler_base /bin/bash

The data is available under /data.

Data removal
------------

Data can be classified between Taler (DBs, keys, logs), and Docker specific
(dangling images, volumes, stopped containers).  Most of Taler data is found
in 'volumes', and can be removed in the following way:

  # From this directory.
  $ docker-compose down -v

Note: the current version does not store config files into volumes, but in
services' containers.

Use the following command to remove stopped containers, dangling images
and build cache, and unused networks.  After its return, the Taler sandbox
can be run again without rebuilding it.

  $ docker system prune

Disk usage can be monitored by the command:

  $ docker system df

Logs
----

Newest rotated logs can be seen by the following command,
from any directory:

  $ docker run -v demo_talerlogs:/logs -it taler_local/taler_base /bin/bash

The started container should now have all the logs under /logs.

How to test on localhost
========================

From this directory:
  
  $ ./test-docker-localhost.sh

The above test registers a new bank account to libEufin,
withdraw coins and spend them directly at the merchant backend.

NOTE: localhost works only with the default ports exposed.

How to deploy to online sites
=============================

Assuming that TLS is already configured, the following
Nginx configuration example deploys this sandbox under
"example.com":

  server {
    server_name exchange.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;
    root /dev/null;
  
    location / {
      proxy_pass http://localhost:5555/;
      proxy_redirect off;
      proxy_set_header Host $host;
    }
  }
  
  server {
    server_name backend.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;
  
    location / {
      proxy_set_header X-Forwarded-Host "backend.example.com";
      proxy_set_header X-Forwarded-Proto "https";
      proxy_set_header X-Forwarded-Prefix "/";
      proxy_pass http://localhost:5556/;
      proxy_redirect off;
      proxy_set_header Host $host;
    }
  }

  server {
    server_name webui-bank.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;

    location = / {
      # Serves the SPA
      index index.html;
      proxy_pass http://localhost:15002/;
    }
  }
  
  server {
    server_name bank.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;

    location / {
      proxy_set_header X-Forwarded-Host "bank.example.com";
      proxy_set_header X-Forwarded-Proto "https";
      proxy_set_header X-Forwarded-Prefix /;
      proxy_pass http://localhost:15000/;
    }
  }

  server {
    server_name blog.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;
   
    location / {
      proxy_set_header X-Forwarded-Host "blog.example.com";
      proxy_set_header X-Forwarded-Proto "https";
      proxy_set_header X-Forwarded-Prefix /;
      proxy_pass http://localhost:5559/;
    }
  }

  server {
    server_name donations.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;
   
    location / {
      proxy_set_header X-Forwarded-Host "donations.example.com";
      proxy_set_header X-Forwarded-Proto "https";
      proxy_set_header X-Forwarded-Prefix /;
      proxy_pass http://localhost:5560/;
    }
  }

  server {
    server_name survey.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;
   
    location / {
      proxy_set_header X-Forwarded-Host "survey.example.com";
      proxy_set_header X-Forwarded-Proto "https";
      proxy_set_header X-Forwarded-Prefix /;
      proxy_pass http://localhost:5561/;
    }
  }

  # Landing page that explains the demo.
  server {
    server_name intro.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;
   
    location / {
      proxy_pass http://localhost:5562/;
    }
  }

  server {
    server_name sync.example.com;
    listen 443 ssl;
    listen [::]:443 ssl;
   
    location / {
      proxy_set_header X-Forwarded-Host "sync.example.com";
      proxy_set_header X-Forwarded-Proto "https";
      proxy_set_header X-Forwarded-Prefix /;
      proxy_pass http://localhost:5563/;
    }
  }