README.md (5404B)
1 # Taler merchant demos 2 3 This repository contains the GNU Taler landing page, essay shop, and donation 4 demo. It is implemented as one self-contained Go executable with no 5 third-party Go dependencies. Templates, translations, styles, and essay 6 content are embedded in the executable. 7 8 ## Build and test 9 10 Go 1.22 or newer is required. 11 12 GNU gettext is also required for the translation maintenance and validation 13 targets. 14 15 Select an installation prefix with the GNU-style configuration entry point: 16 17 ```console 18 $ ./configure --prefix=/usr/local 19 ``` 20 21 The default prefix is `/usr/local`. 22 23 ```console 24 $ make 25 $ make check 26 ``` 27 28 ## Translation maintenance 29 30 Language URLs are canonicalized across all three demos. Regional locales use 31 an exact supported match first, then a supported parent: `/de_CH/` and 32 `/de-CH/` currently redirect to `/de/`. Matching ignores case and treats 33 underscores and hyphens equally. Unknown locale codes redirect to English. 34 Locale redirects preserve the remaining path, query parameters, and forwarded 35 prefix, and use HTTP 307 to preserve form submissions. Missing pages still return 404. 36 The root URL chooses a supported language from `Accept-Language`. 37 38 Bank links use the same language paths as the other demos, for example 39 `https://bank.demo.taler.net/de/`. Sandcastle's Caddy configuration redirects 40 these entry points to the bank UI with the selected language. 41 42 The user interface is available in English, German, French, Italian, 43 Portuguese, Spanish, Russian, Turkish, and Ukrainian. Run the extractor after 44 changing user-facing strings in the Go handlers or templates: 45 46 ```console 47 $ make update-i18n 48 ``` 49 50 This regenerates `messages.pot`, merges it into each retained PO file, and 51 removes obsolete entries. `make check` verifies that the POT is current, that 52 all PO files pass gettext validation, and that placeholders and HTML tags are 53 preserved by every translation. 54 55 The executable is written to `build/taler-merchant-demos`. Install it below 56 the configured prefix with: 57 58 ```console 59 $ make install 60 ``` 61 62 `DESTDIR` is honored for staged installations. The prefix can also be 63 overridden directly with `make prefix=...` without running `configure`. 64 65 ## Configuration 66 67 The server reads the same GNUnet-style configuration used by other Taler 68 components. Section and option names are case-insensitive. `@INLINE@` 69 directives and `$VAR`, `${VAR}`, and `${VAR:-fallback}` filename expansions are 70 supported. 71 72 Pass a configuration explicitly with `-c`. Without it, the server uses the 73 first existing file from `$XDG_CONFIG_HOME/taler-merchant-demos.conf` (or 74 `~/.config/taler-merchant-demos.conf` when `XDG_CONFIG_HOME` is unset), 75 `/etc/taler-merchant-demos.conf`, and 76 `/etc/taler-merchant-demos/taler-merchant-demos.conf`. It proceeds with only 77 defaults when none of these files exists. 78 79 Defaults are loaded first, in filename order, from 80 `$TALER_MERCHANT_DEMOS_BASE_CONFIG`. Without that override, the defaults are 81 read from `share/taler-merchant-demos/config.d` below the installation prefix, 82 which can be overridden with `$TALER_MERCHANT_DEMOS_PREFIX`. Inline files are 83 loaded at the point where their `@INLINE@` directive occurs, and the main 84 configuration is loaded last. 85 86 A configuration containing all three demos looks like this: 87 88 ```ini 89 [taler] 90 currency = KUDOS 91 92 [frontend-demo] 93 landing_url = https://demo.taler.net/ 94 bank_url = https://bank.demo.taler.net/ 95 blog_url = https://shop.demo.taler.net/ 96 donations_url = https://donations.demo.taler.net/ 97 98 [frontend-demo-landing] 99 http_serve = tcp 100 http_port = 8080 101 102 [frontend-demo-blog] 103 http_serve = tcp 104 http_port = 8081 105 backend_url = https://backend.demo.taler.net/instances/blog/ 106 backend_apikey = secret-token:secret 107 enable_tokens = no 108 109 [frontend-demo-donations] 110 http_serve = tcp 111 http_port = 8082 112 backend_url_gnunet = https://backend.demo.taler.net/instances/gnunet/ 113 backend_apikey_gnunet = secret-token:secret 114 backend_url_taler = https://backend.demo.taler.net/instances/taler/ 115 backend_apikey_taler = secret-token:secret 116 backend_url_tor = https://backend.demo.taler.net/instances/tor/ 117 backend_apikey_tor = secret-token:secret 118 # A non-empty legacy value enables tax-receipt output. The Merchant backend's 119 # configured donation authorities determine which authority URLs are offered. 120 donau_url = 121 ``` 122 123 Each section can instead listen on a Unix socket: 124 125 ```ini 126 [frontend-demo-blog] 127 http_serve = unix 128 http_unixpath = /run/taler-merchant-demos/blog.sock 129 http_unixpath_mode = 660 130 ``` 131 132 The command-line `--http-port` option overrides the configured listener and 133 forces TCP mode. 134 135 Inspect the effective configuration, including defaults and inline files. The 136 commented header lists files in load order, and every setting is annotated 137 with its source location: 138 139 ```console 140 $ taler-merchant-demos config dump -c /etc/taler-merchant-demos/taler-merchant-demos.conf 141 ``` 142 143 ## Run 144 145 Choose exactly one demo per process: 146 147 ```console 148 $ taler-merchant-demos -c /etc/taler-merchant-demos/taler-merchant-demos.conf landing 149 $ taler-merchant-demos -c /etc/taler-merchant-demos/taler-merchant-demos.conf blog 150 $ taler-merchant-demos -c /etc/taler-merchant-demos/taler-merchant-demos.conf donations 151 ``` 152 153 When deployed behind a reverse proxy, `X-Forwarded-Host`, 154 `X-Forwarded-Proto`, and `X-Forwarded-Prefix` are used for public fulfillment 155 URLs and generated links. These headers should be removed from untrusted 156 client requests and set by the trusted proxy.