commit 46d6789df8e7c7a195f89c0eb09315b80e019b23
parent ef9ae5c1b76d6995caf6d5f9fb7f8892c2575e4b
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Fri, 19 Sep 2025 15:45:27 +0200
add mailbox manual draft
Diffstat:
5 files changed, 179 insertions(+), 23 deletions(-)
diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst
@@ -21,7 +21,7 @@
Mailbox RESTful API
===================
-This is th for the GNU Taler Mailbox service which allows Taler
+This is the API documentation for the GNU Taler Mailbox service which allows Taler
wallets to securely send push and pull payment requests to other wallets
without having to interact with the respective messaging service.
diff --git a/frags/taldir-maildir-architecture.rst b/frags/taldir-maildir-architecture.rst
@@ -0,0 +1,24 @@
+The following illustrations gives an overview of the
+architecture and the main interactions:
+
+.. image:: images/taldir-mailbox-registration.png
+
+.. image:: images/taldir-mailbox-lookup.png
+
+The user, in this case Alice, first requires a mailbox URI.
+In the case of GNU Taler Mailboxes offered through the mailbox
+service, mailbox URIs can be generated from wallet addresses.
+
+The mailbox URI can then be associated with one or more aliases
+by Alice with the directory service.
+To do so, Alice must prove that she is actually behind a respective
+alias.
+For example, a validation link is sent to Alices email address if she
+wants to associate her email alias with the mailbox URI.
+The validation process differs depending on the alias used.
+
+Other users, in this case Bob, may then resolve the mailbox URI using
+one of Alice's aliases in order to request a payment, or use Alice's
+wallet address to send money.
+
+
diff --git a/index.rst b/index.rst
@@ -64,6 +64,7 @@ Documentation Overview
taler-challenger-manual
taler-auditor-manual
taler-directory-manual
+ taler-mailbox-manual
libeufin/index
depolymerization/index
design-documents/index
diff --git a/taler-directory-manual.rst b/taler-directory-manual.rst
@@ -54,28 +54,7 @@ or learn about known limitations, please check our
Architecture overview
---------------------
-The following illustrations gives an overview of the
-architecture and the main interactions:
-
-.. image:: images/taldir-mailbox-registration.png
-
-.. image:: images/taldir-mailbox-lookup.png
-
-The user, in this case Alice, first requires a mailbox URI.
-In the case of GNU Taler Mailboxes offered through the mailbox
-service, mailbox URIs can be generated from wallet addresses.
-
-The mailbox URI can then be associated with one or more aliases
-by Alice with the directory service.
-To do so, Alice must prove that she is actually behind a respective
-alias.
-For example, a validation link is sent to Alices email address if she
-wants to associate her email alias with the mailbox URI.
-The validation process differs depending on the alias used.
-
-Other users, in this case Bob, may then resolve the mailbox URI using
-one of Alice's aliases in order to request a payment, or use Alice's
-wallet address to send money.
+.. include:: frags/taldir-maildir-architecture.rst
.. _TaldirInstallation:
diff --git a/taler-mailbox-manual.rst b/taler-mailbox-manual.rst
@@ -0,0 +1,152 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2025 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Martin Schanzenbach
+
+Mailbox Operator Manual
+#######################
+
+.. contents:: Table of Contents
+ :depth: 2
+ :local:
+
+
+Introduction
+============
+
+About Taler Mailbox
+-------------------
+
+The Taler Mailbox facilitates sending and receiving payment requests.
+The service does not require any registration and offers limited inbox space
+for any wallet address.
+
+About this manual
+-----------------
+
+This manual targets system administrators who want to install,
+operate or integrate the mailbox service. To report issues
+or learn about known limitations, please check our
+`bug tracker <https://bugs.taler.net>`__.
+
+Architecture overview
+---------------------
+
+.. include:: frags/taldir-maildir-architecture.rst
+
+.. _MaildirInstallation:
+
+Installation
+============
+
+In this guide's shell-session fragments, the command prompt shows two pieces
+of information:
+
+* Who is performing the command
+ (``$user`` vs ``root``, and ending character ``$`` vs ``#``).
+
+
+Installing from source
+----------------------
+
+The following instructions will show how to install libgnunetutil and
+the core GNU Taler libraries from source.
+
+The package sources can be find in our
+`download directory <http://ftpmirror.gnu.org/taler/>`__.
+
+GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format.
+The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match.
+Exceptions to this general rule are documented in the release notes.
+For example, taler-mailbox 1.3.0 should be compatible with Taler exchange 1.4.x
+as the MAJOR version matches. A MAJOR version of 0 indicates experimental
+development, and you are expected to always run all of the *latest* releases
+together (no compatibility guarantees).
+
+First, the following packages need to be installed before we can compile the
+backend:
+
+- Golang >= 1.19
+
+Installing the mailbox binary packages on Debian
+------------------------------------------------
+
+.. include:: frags/installing-debian.rst
+
+To install taler-mailbox you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-mailbox
+
+Note that the package does not perform any configuration work except for
+setting up the various users and the systemd service scripts. You still must
+configure at least the database, HTTP reverse proxy (typically with TLS
+certificates) and the terms of service.
+
+Installing the GNU Taler binary packages on Trisquel
+----------------------------------------------------
+
+.. include:: frags/installing-trisquel.rst
+
+Installing the GNU Taler binary packages on Ubuntu
+--------------------------------------------------
+
+.. include:: frags/installing-ubuntu.rst
+
+To install the Taler exchange, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-mailbox
+
+Note that the package does not perform any configuration work except for
+setting up the various users and the systemd service scripts. You still must
+configure at least the database, HTTP reverse proxy (typically with TLS
+certificates), and the terms of service.
+
+
+Services, users, groups and file system hierarchy
+-------------------------------------------------
+
+The *taler-mailbox* package will use several system users
+to compartmentalize different parts of the system:
+
+* ``mailbox-httpd``: runs the HTTP daemon with the core business logic.
+* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
+* ``www-data``: runs the frontend HTTPS service with the TLS keys (from *nginx* package).
+
+The package will deploy a systemd service files in
+``/usr/lib/systemd/system/`` for taler-mailbox:
+
+* ``taler-mailbox.service``: the business logic with the public REST API.
+
+
+Configuration Fundamentals
+==========================
+
+This chapter provides fundamental details about the exchange configuration.
+
+The configuration for all Taler components uses a single configuration file
+as entry point: ``/etc/mailbox/mailbox.conf``.
+
+System defaults are automatically loaded from files in
+``/usr/share/mailbox/config.d``. These default files should never be modified.
+
+The default configuration ``mailbox.conf`` configuration file also includes all
+configuration files in ``/etc/mailbox/conf.d``.
+
+.. include:: frags/configuration-format.rst
