taler-mailbox-manual.rst (4879B)
1 .. 2 This file is part of GNU TALER. 3 4 Copyright (C) 2025 Taler Systems SA 5 6 TALER is free software; you can redistribute it and/or modify it under the 7 terms of the GNU Affero General Public License as published by the Free Software 8 Foundation; either version 2.1, or (at your option) any later version. 9 10 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 11 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 12 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 13 14 You should have received a copy of the GNU Affero General Public License along with 15 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 16 17 @author Martin Schanzenbach 18 19 Mailbox Operator Manual 20 ####################### 21 22 Introduction 23 ============ 24 25 About Taler Mailbox 26 ------------------- 27 28 The Taler Mailbox facilitates sending and receiving payment requests. 29 The service does not require any registration and offers limited inbox space 30 for any wallet address. 31 32 About this manual 33 ----------------- 34 35 This manual targets system administrators who want to install, 36 operate or integrate the mailbox service. To report issues 37 or learn about known limitations, please check our 38 `bug tracker <https://bugs.taler.net>`__. 39 40 Architecture overview 41 --------------------- 42 43 .. include:: frags/taldir-maildir-architecture.rst 44 45 .. _MaildirInstallation: 46 47 Installation 48 ============ 49 50 In this guide's shell-session fragments, the command prompt shows two pieces 51 of information: 52 53 * Who is performing the command 54 (``$user`` vs ``root``, and ending character ``$`` vs ``#``). 55 56 57 Installing from source 58 ---------------------- 59 60 The following instructions will show how to install libgnunetutil and 61 the core GNU Taler libraries from source. 62 63 The package sources can be find in our 64 `download directory <http://ftpmirror.gnu.org/taler/>`__. 65 66 GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format. 67 The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match. 68 Exceptions to this general rule are documented in the release notes. 69 For example, taler-mailbox 1.3.0 should be compatible with Taler exchange 1.4.x 70 as the MAJOR version matches. A MAJOR version of 0 indicates experimental 71 development, and you are expected to always run all of the *latest* releases 72 together (no compatibility guarantees). 73 74 First, the following packages need to be installed before we can compile the 75 backend: 76 77 - Golang >= 1.19 78 79 Installing the mailbox binary packages on Debian 80 ------------------------------------------------ 81 82 .. include:: frags/installing-debian.rst 83 84 To install taler-mailbox you can now simply run: 85 86 .. code-block:: shell-session 87 88 # apt install taler-mailbox 89 90 Note that the package does not perform any configuration work except for 91 setting up the various users and the systemd service scripts. You still must 92 configure at least the database, HTTP reverse proxy (typically with TLS 93 certificates) and the terms of service. 94 95 Installing the GNU Taler binary packages on Trisquel 96 ---------------------------------------------------- 97 98 .. include:: frags/installing-trisquel.rst 99 100 Installing the GNU Taler binary packages on Ubuntu 101 -------------------------------------------------- 102 103 .. include:: frags/installing-ubuntu.rst 104 105 To install the Taler exchange, you can now simply run: 106 107 .. code-block:: shell-session 108 109 # apt install taler-mailbox 110 111 Note that the package does not perform any configuration work except for 112 setting up the various users and the systemd service scripts. You still must 113 configure at least the database, HTTP reverse proxy (typically with TLS 114 certificates), and the terms of service. 115 116 117 Services, users, groups and file system hierarchy 118 ------------------------------------------------- 119 120 The *taler-mailbox* package will use several system users 121 to compartmentalize different parts of the system: 122 123 * ``mailbox-httpd``: runs the HTTP daemon with the core business logic. 124 * ``postgres``: runs the PostgreSQL database (from *postgresql* package). 125 * ``www-data``: runs the frontend HTTPS service with the TLS keys (from *nginx* package). 126 127 The package will deploy a systemd service files in 128 ``/usr/lib/systemd/system/`` for taler-mailbox: 129 130 * ``taler-mailbox.service``: the business logic with the public REST API. 131 132 133 Configuration Fundamentals 134 ========================== 135 136 This chapter provides fundamental details about the exchange configuration. 137 138 The configuration for all Taler components uses a single configuration file 139 as entry point: ``/etc/mailbox/mailbox.conf``. 140 141 System defaults are automatically loaded from files in 142 ``/usr/share/mailbox/config.d``. These default files should never be modified. 143 144 The default configuration ``mailbox.conf`` configuration file also includes all 145 configuration files in ``/etc/mailbox/conf.d``. 146 147 .. include:: frags/configuration-format.rst