README.md (4518B)
1 <!-- 2 This file is part of GNU Taler 3 (C) 2026 Taler Systems S.A. 4 5 GNU Taler is free software; you can redistribute it and/or modify it under the 6 terms of the GNU General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU General Public License for more details. 12 13 You should have received a copy of the GNU General Public License along with 14 GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 --> 16 17 # Services beside the stack 18 19 `taler-unified-setup.sh` brings up the exchange, the merchant, the bank, donau 20 and the auditor. Two more services the wallet can use are not part of it, and 21 the wallet has screens for both: 22 23 | service | repository | port | what it unlocks in the app | 24 | --- | --- | --- | --- | 25 | Taler mailbox | `git://git.taler.net/taler-mailbox` | 11000 | the Mailbox screen: register, list, refresh, delete | 26 | Taler directory | `git://git.taler.net/taldir` | 11001 | nothing, see below — but it makes the contacts operations testable through wallet-core | 27 28 Both are Go services with vendored dependencies, so they build without network 29 access to a module proxy — but they need **Go 1.25**, which Debian does not 30 have yet; `GOTOOLCHAIN=auto` (the default) downloads it: 31 32 ```bash 33 git clone git://git.taler.net/taler-mailbox && cd taler-mailbox 34 GOFLAGS=-mod=vendor go build -ldflags "-X main.ltversion=1:1:0" -o /tmp/ ./cmd/... 35 ``` 36 37 The `ltversion` ldflag matters: without it the service advertises an empty 38 protocol version and the wallet refuses it (`carefullyParseConfig`). 39 40 ## Deploying them 41 42 The simulator runs them on the emulator host, beside the stack: 43 44 ``` 45 /opt/taler-mailbox/{mailbox-server,mailbox-dbinit,sim.conf} 46 /opt/taldir/{taldir-server,taldir-dbinit,sim.conf,sim-validator.sh} 47 ``` 48 49 `services/mailbox-sim.conf` and `services/taldir-sim.conf` here are the 50 deployed configurations. Databases are Postgres, created once: 51 52 ```bash 53 createdb -h /var/run/postgresql talermailbox 54 createdb -h /var/run/postgresql talerdir 55 cd /opt/taler-mailbox && ./mailbox-dbinit -c sim.conf 56 cd /opt/taldir && ./taldir-dbinit -c sim.conf 57 cd /opt/taler-mailbox && ./mailbox-server -c sim.conf -L DEBUG > /tmp/mb.log 2>&1 & 58 cd /opt/taldir && ./taldir-server -c sim.conf -L DEBUG > server.log 2>&1 & 59 ``` 60 61 They keep their own databases, so unlike `exchange2` they survive a stack 62 restart and need starting only once. Their ports are in `stack.sh`'s port list, 63 so `emu.sh reverse` maps them into every emulator. 64 65 ## Things that cost an hour each 66 67 * **`localhost` is not `127.0.0.1`.** Both services bind `127.0.0.1` only, and 68 wallet-core resolves `localhost` to `::1` first, so a `localhost` URL gets 69 ECONNREFUSED. Use the numeric address in anything handed to wallet-core. 70 * **Every `GetDuration`/`GetAmount` in the mailbox server errors out when its 71 key is missing**, default or no default, so `sim.conf` spells out every fee 72 and every duration. 73 * **`taldir-dbinit` reads `[taldir-pq]` while `taldir-server` reads 74 `[directory-pq]`.** The config carries both, saying the same thing. 75 * **The directory's protocol version is a literal `0:0:0`** in 76 `pkg/taldir/taldir.go`, which the wallet refuses; the deployment patches it 77 to `1:0:0`. See `findings/taldir-protocol-version-mismatch.md`. 78 * **The email validator is a command.** `[directory-validator-email] COMMAND` 79 is run as `COMMAND <alias> <challenge> <topic> <message>`, so 80 `sim-validator.sh` appends the alias and the challenge to 81 `/opt/taldir/challenges.log` — the simulator's stand-in for reading a 82 validation email, and the only way a scenario can complete a registration. 83 84 ## Why the directory unlocks nothing in the app 85 86 The app hard-codes `https://taldir.gnunet.org` in two files, so no deployment 87 can be reached from it; the service is still worth having, because wallet-core 88 takes the base URL as a parameter and the three contact operations can be 89 driven through `taler-wallet-cli advanced api`. See 90 `findings/alias-registration-hardcodes-the-directory.md`. 91 92 ## Sync 93 94 `git://git.taler.net/sync` is *not* deployed: the Android wallet has no backup 95 or sync feature at all — no screens, and none of the wallet-core backup 96 operations appear in `coverage/app-operations.txt`. Deploying it would add 97 nothing to drive.