commit 6e8685a96572b81693b7823943848090f31a6ad8
parent 3374b425be0b4f9a65e8a547f9f1f9533451c7fd
Author: Antoine A <>
Date: Fri, 3 Apr 2026 18:41:42 +0200
anps: add manual
Diffstat:
2 files changed, 237 insertions(+), 0 deletions(-)
diff --git a/index.rst b/index.rst
@@ -99,6 +99,7 @@ and overall usage of the different Taler components in text and video formats.
taler-auditor-manual
taler-directory-manual
taler-mailbox-manual
+ taler-apns-relay-manual
.. toctree::
:maxdepth: 1
diff --git a/taler-apns-relay-manual.rst b/taler-apns-relay-manual.rst
@@ -0,0 +1,235 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2026 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 Antoine d'Aligny
+
+.. target audience: operator, developer
+
+APNs Relay Manual
+#################
+
+taler-apns-relay is an Apple Push Notification relay. It send a background
+notification to registered devices at a regula interval to wakup an application and enable recurrent background sync.
+
+This manual targets system administrators who want to install and
+operate an APNs relay.
+
+
+.. contents:: Table of Contents
+ :depth: 1
+ :local:
+
+Installation
+============
+
+Installing on Debian
+--------------------
+
+.. include:: frags/installing-debian.rst
+
+To install the adapter, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-apns-relay
+
+Installing on Ubuntu
+--------------------
+
+.. include:: frags/installing-ubuntu.rst
+
+To install the adapter, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-apns-relay
+
+Building from source
+--------------------
+
+APNs Relay belongs to the Taler Rust project, and can be downloaded via Git:
+
+.. code-block:: console
+
+ $ git clone git://git.taler.net/taler-rust
+ $ cd taler-rust
+
+You will need the latest version of the rust stable toolchain and a C toolchain:
+
+.. code-block:: console
+
+ $ sudo apt install rustup build-essential
+ $ rustup toolchain install stable
+
+Then from top-level run:
+
+.. code-block:: console
+
+ $ ./bootstrap
+
+To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services:
+
+.. code-block:: console
+
+ $ sudo apt install debhelper
+ $ make deb
+ $ sudo dpkg -i ../taler-apns-relay*.deb
+
+If the previous steps succeeded, the ``taler-apns-relay`` command should be found in the $PATH.
+
+Services, users, groups and file system hierarchy
+-------------------------------------------------
+
+The *taler-apns-relay* package will create several system users
+to compartmentalize different parts of the system:
+
+* ``taler-apns-relay-httpd``: runs the HTTP daemon with the API logic.
+* ``taler-apns-relay-worker``: runs the worker daemon interacting with the APNs API.
+* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
+
+The adapter setup uses the following system groups:
+
+* ``taler-apns-relay-db``: group for all adapter users with direct database access, specifically taler-apns-relay-httpd and taler-apns-relay-worker.
+
+The package will deploy systemd service files in
+``/usr/lib/systemd/system/`` for the various components:
+
+* ``taler-apns-relay-httpd.service``: registration REST API.
+* ``taler-apns-relay-httpd.socket``: systemd socket activation for the HTTP daemon.
+* ``taler-apns-relay-worker.service``: worker deamon interacting with the APNs API.
+* ``taler-apns-relay.target``: main target for the relay to be operational.
+
+The deployment creates the following key locations in the system:
+
+* ``/etc/taler-apns-relay/``: configuration files.
+* ``/run/taler-apns-relay/``: contains the UNIX domain sockets for inter-process communication (IPC).
+
+Configuration Fundamentals
+==========================
+
+This chapter provides fundamental details about the adapter configuration.
+
+The configuration for all adapter components uses a single configuration file
+as entry point: ``/etc/taler-apns-relay/taler-apns-relay.conf``.
+
+System defaults are automatically loaded from files in
+``/usr/share/taler-apns-relay/config.d``.
+These default files should never be modified.
+
+The default configuration ``taler-apns-relay.conf`` configuration file
+also includes all configuration files in ``/etc/taler-apns-relay/conf.d``.
+The settings from files in
+``conf.d`` are only relevant to particular components of an adapter, while
+``taler-apns-relay.conf`` contains settings that affect all adapter components.
+
+
+The directory ``/etc/taler-apns-relay/secrets`` contains configuration file snippets with
+values that should only be readable to certain users. They are included with the ``@inline-secret@``
+directive and should end with ``.secret.conf``.
+
+To view the entire configuration annotated with the source of each configuration option, you
+can use the ``taler-apns-relay config`` helper:
+
+.. code-block:: shell-session
+
+ # taler-apns-relay config dump --diagnostics
+
+Basic Setup
+===========
+
+Database setup
+--------------
+
+The configuration file must include a connection string that tells the adapter how it should connect to the database. The default
+is:
+
+.. code-block:: ini
+ :caption: /etc/taler-apns-relay/secrets/apns-relay-db.secret.conf
+
+ [apns-relaydb-postgres]
+ config = postgres:///taler-apns-relay
+
+If the database is run on a different host, please follow the instructions
+from the PostgreSQL manual for configuring remote access.
+
+Assuming the configuration is correct, the following
+command initializes (or upgrades) the database schema using:
+You can then use a script to automate a secure database setup:
+
+.. code-block:: console
+
+ # taler-apns-relay-dbconfig
+
+Worker setup
+------------
+
+You will need an `Apple private key <https://developer.apple.com/help/account/manage-keys/create-a-private-key/>`.
+Update the configuration files:
+
+.. code-block:: ini
+ :caption: /etc/taler-apns-relay/secret/apns-relay-worker.secret.conf
+
+ [apns-relay-worker]
+ KEY_ID = 555CFX5XXX
+ TEAM_ID = GDDDQ9418X
+ BUNDLE_ID = com.taler-systems.talerwallet
+
+Copy the private key .p8 file to the configured path ``KEY_FILE`` (``/var/lib/taler-apns-relay/key.p8`` with the default config).
+
+Make sure this file is accessible to the user running ``taler-apns-relay-worker``, for the default services you should run:
+
+.. code-block:: console
+
+ $ chown taler-apns-relay-worker:taler-apns-relay-worker /var/lib/taler-apns-relay/key.p8
+
+And then run the setup process:
+
+.. code-block:: console
+
+ $ sudo -u taler-apns-relay-worker taler-apns-relay -c /etc/taler-apns-relay/taler-apns-relay.conf setup
+
+Deployment
+==========
+
+This chapter describes how to deploy the adapter once the basic installation
+and configuration are completed.
+
+Reverse Proxy Setup
+-------------------
+
+By default, the ``taler-apns-relay-httpd`` service listens for HTTP connections
+on a UNIX domain socket. To make the service publicly available, a reverse
+proxy such as nginx should be used. We strongly recommend to configure nginx
+to use TLS.
+
+The ``taler-apns-relay`` package ships with a sample configuration that can be
+enabled in nginx:
+
+.. code-block:: shell-session
+
+ # vim /etc/nginx/sites-available/taler-apns-relay
+ < ... customize configuration ... >
+ # ln -s /etc/nginx/sites-available/taler-apns-relay /etc/nginx/sites-enabled/taler-apns-relay
+ # systemctl reload nginx
+
+With this last step, we are finally ready to launch the
+main adapter process.
+
+Launching the relay
+-------------------
+
+.. code-block:: console
+
+ # systemctl enable --now taler-apns-relay.target
+\ No newline at end of file
