diff options
Diffstat (limited to 'sandcastle/README')
| -rw-r--r-- | sandcastle/README | 292 |
1 files changed, 0 insertions, 292 deletions
diff --git a/sandcastle/README b/sandcastle/README deleted file mode 100644 index 1a89c22..0000000 --- a/sandcastle/README +++ /dev/null @@ -1,292 +0,0 @@ -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 rewards -================ - -The following command (executed from the container CLI) manually creates a rewards 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 the rewards 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 rewards reserves, run: - -$ taler-harness deployment tip-cleanup --merchant-url https://backend.demo.taler.net/instances/survey/ --merchant-apikey=$MERCHANT_APIKEY - -[*] - To enable the "rewards balance checking" script. Please execute after doing the "docker compose up" the next command from, -the "deployment/sandcastle" directory. - -./utils/enable-services.sh - -This will put to run a systemd service, which will check the rewards balance once per week (this can be change editing -the systemd/fund-rewards.timer). - -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. - -How to save and restore Docker images -===================================== - -When certain deployment is fully working on test.taler.net, and therefore is going -to be deployed in demo.taler.net, you should save those docker working images, as -mean of backup. - -How to save working Docker images ---------------------------------- - -To save each --good image of each component you can execute the script "save-good.sh" without any -arguments. This script will create some tagged docker images with the current timestamp - -This way, if something goes wrong with newly created images, you can use these previous good images, to -re-deploy the GNU Taler program. - -How to recover saved images ---------------------------- - -In order to use them, after the manual creation of the wrong ones, you should execute the -script "restore-good.sh". - -Thus, to restore previously created images, you should provide a -timestamp as an option, to the "restore-good.sh" script. - -Example: ./restore-good.sh 1693812987 - -To get the timestamp (which was previously generated by save-good.sh), you can execute this command: - -docker images #having as result "taler_local/taler_base:good-$TIMESTAMP" - -Then whenever you know about the precise timestamp, you can type "./restore-good.sh <TIMESTAMP>" - -[*] - Warning - -This method of saving docker images and restoring them, won't work, if after executing -save-good.sh, you do a server cleanup with "docker system prune -a or --all" - -Doing a "docker system prune" without the "-a" option, it's okay. - -Eventually as a future improvement, we might configure "docker registry", to -store safely all these good and stable docker images. - -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 -============================= - -Before deploying the sandcastle setup, you need to undertake certain replacements within -the configuration file "config/deployment.conf". - -currency = KUDOS (or the name of your currency) -merchant-url = https://backend.domain.tld -landing-url = https://domain.tld/ -blog-url = https://shop.domain.tld/ -donations-url = https://donations.domain.tld/ -survey-url = https://survey.domain.tld/ -sync-url = https://sync.domain.tld/ -bank-url = https://bank.domain.tld/ -bank-backend-url = https://bank.domain.tld/demobanks/default/ - -After doing this, and assuming that TLS is already configured, you can use the file named -"nginx-example.conf" on the sandcastle directory, as a NGINX virtual host, replacing -the domain name "example.com" with your own domain name. - -You can use the SED command to replace this automatically as this, being located within - the sandcastle directory beforehand: - -sed -i "s/example.com/yourdomain.com/g" nginx-example.conf - -TLS Configuration -=================== - -For the sake of simplicity we recommend CERBOT as a mean to obtain the Let's Encrypt -certificates. - -First install the CERTBOT program following the instructions from https://certbot.eff.org/ - -After you have correctly installed CERTBOT, just execute "certbot --nginx" to obtain -the necessary certificates to use the https protocol, and have them renewed automatically - every 90 days. - - - |