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