sandcastle-ng

README.md (12802B)

---

 # Introduction
 
 The sandcastle is a containerized deployment of GNU Taler
 
 It uses podman to build an image and run a single container that
 has systemd running inside.
 
 
 # Prerequisites
 
 You need (on your host system):
 
 * podman
 * bash
 * Python 3.10 or newer
 
 The sandcastle-ng container exposes the GNU Taler APIs and Web interfaces
 through Unix domain sockets.
 
 Some of these services expect to be accessed via a certain hostname,
 so it is recommended that you set up the following domain names:
 
 * `exchange.$MYDOMAIN` for taler-exchange
 * `backend.$MYDOMAIN` for taler-merchant
 * `bank.$MYDOMAIN` for libeufin-bank
 * `landing.$MYDOMAIN` for the demo landing page
 * `shop.$MYDOMAIN` for the demo blog shop page
 * `donations.$MYDOMAIN` for the demo donations page
 * `paivana.$MYDOMAIN` for the demo Paivana paywall
 
 Your host system should reverse-proxy HTTP(s) traffic to the respective service
 socket.
 
 
 # Upgrading Component Versions
 
 `packages.toml` is the single source of truth for package repositories, tags,
 Debian paths, dependencies, enabled state, and builders.  It uses the same
 `[repositories]` and `[packages]` layout as
 `taler-deployment/packaging/ng/packages.toml`.
 
 Run `./sandcastle-upgrade` to update package tags in `packages.toml` to the
 latest upstream tag of the respective repository.
 
 By default only production tags (`vX.Y.Z`, `deb-vX.Y.Z-R`) are considered.
 Pass `--dev` to also consider dev tags (`vX.Y.Z-dev.N`).
 Pass `--dry` to only show what would change.
 Individual components can be given as arguments, e.g.
 
     ./sandcastle-upgrade --dev taler-exchange gnunet
 
 Packages whose configured tag is not a supported version tag are left alone.
 Use `./sandcastle-upgrade --dry` to show available updates without changing the
 configuration.
 
 
 # Building the Container Image
 
 1. Set the package's `tag` in `packages.toml` to the git tag you want to build.
 
 2. Run `./sandcastle-build` to build the Taler container.  The resulting container
    will be tagged as `taler-base-all`.
 
    Package builds are incremental.  Built Debian packages and their build keys
    are kept below `packages/`, while downloaded build data is kept below
    `cache/`.  A component is rebuilt when its resolved package configuration,
    build logic, builder image, or one of its package dependencies changes.
    Unrelated packages remain untouched.  Failed builds are not recorded as
    current, so they are retried on the next invocation.
 
    Packages using the `pnpm-workspace` builder are grouped by repository and
    tag.  Each group clones and bootstraps the monorepo once, performs one
    filtered pnpm install and build for all selected workspace dependency
    closures, and then creates the individual Debian packages from the prebuilt
    artifacts.
 
    Apt, pnpm, Gradle, Cargo, npm, Go, and pip caches are shared between package
    containers.  Source checkouts and package build trees remain fresh.
 
    Use `./sandcastle-build --no-cache` to rebuild the package builder, every
    component package, and the final image without cached image layers.  Shared
    dependency and compiler caches are retained.
 
    By default `sandcastle-build` builds from the `Dockerfile`
    in the same directory as the script.
    Anyhow you can pass a different container file like this:
 
        ./sandcastle-build nightly.Dockerfile
 
 
 # Configuring the Deployment
 
 If you just want to play around with the Taler services inside the container,
 or want to get an integration development environment,
 there is a nice preset, see below.
 Thus in these cases no configuration is required
 and you can skip to "Running the Deployment" below.
 
 For Taler developers, it is recommended that for each sandcastle deployment,
 you clone the sandcastle-ng.git repository
 (https://git.taler.net/sandcastle-ng.git) and create a branch with
 deployment-specific changes.
 
 Currently there is not much configuration.
 
 The main adjustments to be made are:
 
 * scripts/demo/setup-sandcastle.sh has the currency on top of the file
 * Services use Unix sockets below `sockets/` by default.  Set
   `SANDCASTLE_SOCKET_DIR` to choose a different host directory.
 
 To make adjustments for an environment without changing the
 ``setup-sandcastle.sh`` script, you can use an override file
 ``overrides/$YOUR_ENVIRONMENT``.  This is a bash script that is sourced at the
 beginning of ``setup-sandcastle.sh`` and can be used to customize
 environment-specific settings such as hostnames.
 
 In order to choose an override,
 set the ``SANDCASTLE_OVERRIDE_NAME`` environment variable
 before running `./sandcastle-run`:
 
     SANDCASTLE_OVERRIDE_NAME=$YOUR_ENVIRONMENT ./sandcastle-run
 
 
 The following variables are typically adjusted in an override file:
 
 * ``CURRENCY``: Currency of the deployment
 * ``MYDOMAIN``: Parent domain name for ``{bank,exchange,backend}`` services.
 * ``EXTERNAL_PORT``: The host port the services will be available on.
 * ``EXTERNAL_IP``: The host IP the services will be available on.
   For security reasons this defaults to localhost (127.0.0.1).
 * ``USE_INSECURE_SANDBOX_PASSWORDS``:
     If set to `1`, use password `sandbox` for all services instead of random ones.
     WARNING! Use only when listening to localhost!
 * ``PAIVANA_DESTINATION``: Upstream website that the Paivana paywall
   protects.  Defaults to `https://www.taler.net/`.  Note that this is an
   *external* server that the container proxies to, it is not served by the
   sandcastle itself.
 * ``ENABLE_KYC``: Set to `1` to enable KYC; it is disabled by default.
 * ``ENABLE_TURNSTILE``: Set to `0` to omit the Drupal Turnstile setup; it is
   enabled by default.
 
 
 # Running the Deployment
 
 Run ``./sandcastle-run`` to run the single container.
 The container will be named `taler-sandcastle`.
 Wait until everything has been set up:
 
     ./sandcastle-wait
 
 While provisioning is running, this follows the output of
 ``setup-sandcastle.service`` inside the container.  It exits successfully once
 provisioning has completed, or with a non-zero status if provisioning fails.
 After a successful deployment, the landing host serves the Sandcastle version,
 component versions, and deployment time at ``/metrics/sandcastle-status``.
 
 Note that ``./sandcastle-run`` is just a wrapper around ``podman run``.
 If required, you can pass addtional arguments to ``./sandcastle-run``.
 These will be passed on to ``podman run``. Example:
 
     ./sandcastle-run --log-level=debug
 
 The running container exposes these services through bind-mounted Unix sockets:
 
 | Service | Socket |
 | --- | --- |
 | Bank | `bank.sock` |
 | Exchange | `exchange.sock` |
 | Merchant backend | `merchant-backend.sock` |
 | Landing page | `landing.sock` |
 | Blog shop | `blog.sock` |
 | Donations | `donations.sock` |
 | Challenger | `challenger.sock` |
 | Auditor | `auditor.sock` |
 | Donau | `donau.sock` |
 | Drupal | `drupal.sock` |
 | Paivana | `paivana.sock` |
 
 Exchange, Merchant, the Blog and Donations demos, Auditor, Donau, and Paivana
 are exposed directly through their native listener or packaged systemd socket
 activation.  Caddy owns the bank socket to bridge libeufin-bank's internal TCP
 listener, the landing socket to add the Sandcastle status endpoint, the
 Challenger socket to serve the insecure demo challenges, and the Drupal socket
 because it is Drupal's HTTP server.
 
 For example, query the Exchange and merchant configuration endpoints with:
 
     curl --unix-socket ./sockets/exchange.sock http://localhost/config
     curl --unix-socket ./sockets/merchant-backend.sock http://localhost/config
 
 The socket directory defaults to `./sockets`, relative to the repository, and
 can be changed when starting the deployment:
 
     SANDCASTLE_SOCKET_DIR=/run/taler-sandcastle ./sandcastle-run
 
 Missing socket directories are created with mode `1777`, and the sockets have
 mode `0666`, so a host reverse proxy running as a different user can connect to
 them.  A pre-existing custom directory must allow the relevant container
 service users to create sockets.  The bind mount uses Podman's shared SELinux
 label; deployments with a confined host reverse proxy may additionally need
 an appropriate local SELinux policy.
 
 libeufin-bank does not yet support Unix sockets, so it listens on localhost
 inside the container and Caddy exposes it through `bank.sock`.
 
 Overrides that define `EXTERNAL_PORT`, such as `taler.localhost`, continue to
 publish that single Caddy ingress port for local integration testing.
 
 When starting sandcastle like
 
     SANDCASTLE_OVERRIDE_NAME=taler.localhost ./sandcastle-run
 
 the services will be available as
 
  - http://taler.localhost:4321
  - http://bank.taler.localhost:4321
  - http://shop.taler.localhost:4321
  - http://donations.taler.localhost:4321
  - http://backend.taler.localhost:4321  - the merchant backend
  - http://exchange.taler.localhost:4321
  - http://auditor.taler.localhost:4321
  - http://challenger.taler.localhost:4321
  - http://paivana.taler.localhost:4321/en/  - www.taler.net behind a Taler paywall
    (use the ``/en/`` entry point, as www.taler.net redirects ``/`` to its own domain)
 
 This gives a nice environment for integration testing.
 
 
 # Running the Unit Tests
 
 Run the Python unit-test suite from the repository root:
 
     python3 -m unittest discover -s tests -v
 
 
 # Stopping the deployment
 
 For stopping the deployment simply run
 
 ```
 ./sandcastle-stop
 ```
 
 which is just a shortcut for ``podman stop taler-sandcastle``.
 
 
 # Watching Logs
 
 Run ``./sandcastle-logs`` to watch the logs within the container.
 You can pass addtional arguments to ``./sandcastle-logs``,
 which will be passed on to ``journalctl`` in the container.  Example:
 
     ./sandcastle-logs --output=cat
 
 
 # Poking Around
 
 You can poke around in a running sandcastle instance by running
 
 ```
 podman exec -it taler-sandcastle /bin/bash
 ```
 
 Or, as a shortcut:
 
 ```
 ./sandcastle-enter
 ```
 
 This will drop you into a shell inside the running container,
 where you have access to systemd, journalctl, etc.
 
 
 # Data Storage
 
 All persistent data is stored in a podman volume called
 _talerdata_.  You can see where it is in your filesystem
 by running ``podman volume inspect talerdata``.
 
 That volume also contains the postgres database files.
 
 ## Cleaning the Data Storage
 
 For cleaning the data storage run
 
     ./sandcastle-plow
 
 and for cleaning also the persistent storage run
 
     ./sandcastle-plow all
 
 
 # Provisioning Details
 
 The whole deployment is configured by a script
 mounted into the container as ``/provision/setup-sandcastle.sh``.
 This script will be run as a oneshot systemd service and will disable itself after
 the first success.
 
 To troubleshoot, run ``journalctl -u setup-sandcastle.service``.
 
 There are different setup scripts in the ``scripts/$SANDCASTLE_SETUP_NAME``
 folders. Specifically:
 
 * ``none`` does no setup at all
 * ``demo`` set up the usual Taler demo
 * TBD: ``regio`` is a currency conversion setup
 
 By default, ``demo`` is used.
 To mount a different provision script,
 set ``$SANDCASTLE_SETUP_NAME`` when running ``./sandcastle-run``,
 like this
 
     SANDCASTLE_SETUP_NAME=none ./sandcastle-run
 
 
 You can always manually run any of the provisioning script inside the container as
 ``/scripts/$SANDCASTLE_SETUP_NAME/setup-sandcastle.sh``.
 
 # Importing / exporting
 
 To migrate a sandcastle deployment, export / import can be used.
 
 ```
 # Requires taler-sandcastle to be running.
 # Export the sandcastle data to ./exported/
 ./sandcastle-export
 
 # Other host:
 # Request an import
 touch exported/import-request
 # Now the deployment script will pick up the data to import
 ./sandcastle-run
 ```
 
 # Neat Things That Already Work
 
 * Rebulding the base image is incremental, since we use layers.  If the tag
   of the exchange is changed, only the exchange and components that depend
   on it are rebuilt.
 * Inside the container, the service names resolve to localhost,
   and on localhost a reverse proxy with locally signed certificates
   ensures that services can talk to each other *within* the container
   by using their *public* base URL.
 
 
 # Future Extensions
 
 * Better way to access logs, better way to expose errors during provisioning
 * The Dockerfile should introduce nightly tags for debian packages it builds.
   Currently it just uses the latest defined version, which is confusing.
 * Deploy the Taler woocommerce plugin, wordpress plugin, Joomla plugin
 * Do self-tests of the deployment using the wallet CLI
 * Running the auditor
 * Running a currency conversion setup with multiple libeufin-bank instances
 * Instead of requiring the reverse proxy to handle TLS,
   the sandcastle container itself could do TLS termination with caddy.
 * To improve performance, allow connecting to an external database
 * Make it easy to import and export the persistent data
 * Extra tooling to checkpoint images/containers to revert to a previous
   state quickly.