taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

taler-apns-relay-manual.rst (7593B)


      1 ..
      2   This file is part of GNU TALER.
      3   Copyright (C) 2026 Taler Systems SA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero General Public License as published by the Free Software
      7   Foundation; either version 3.0, or (at your option) any later version.
      8 
      9   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 Affero General Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero General Public License along with
     14   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 
     16   @author Antoine d'Aligny
     17 
     18 .. target audience: operator, developer
     19 
     20 APNs Relay Manual
     21 #################
     22 
     23 taler-apns-relay is an Apple Push Notification relay. It sends a background
     24 notification to registered devices at a regular interval to wake up an application and enable recurrent background sync.
     25 
     26 This manual targets system administrators who want to install and
     27 operate an APNs relay.
     28 
     29 
     30 .. contents:: Table of Contents
     31   :depth: 1
     32   :local:
     33 
     34 Installation
     35 ============
     36 
     37 Installing on Debian
     38 --------------------
     39 
     40 .. include:: frags/installing-debian.rst
     41 
     42 To install the adapter, you can now simply run:
     43 
     44 .. code-block:: shell-session
     45 
     46   # apt install taler-apns-relay
     47 
     48 Installing on Ubuntu
     49 --------------------
     50 
     51 .. include:: frags/installing-ubuntu.rst
     52 
     53 To install the adapter, you can now simply run:
     54 
     55 .. code-block:: shell-session
     56 
     57   # apt install taler-apns-relay
     58 
     59 Building from source
     60 --------------------
     61 
     62 APNs Relay belongs to the Taler Rust project, and can be downloaded via Git:
     63 
     64 .. code-block:: console
     65 
     66   $ git clone git://git.taler.net/taler-rust
     67   $ cd taler-rust
     68 
     69 Building Debian/Ubuntu packages requires the distribution packages ``cargo``
     70 and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git:
     71 
     72 .. code-block:: console
     73 
     74   $ sudo apt install cargo rustc build-essential python3 git debhelper
     75 
     76 If your distribution provides an older ``rustc``, install newer distribution
     77 packages before continuing. A toolchain installed only through ``rustup`` does
     78 not satisfy the Debian package build dependencies.
     79 
     80 Then from top-level run:
     81 
     82 .. code-block:: console
     83 
     84   $ ./bootstrap
     85 
     86 To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services:
     87 
     88 .. code-block:: console
     89 
     90   $ make deb
     91   $ sudo dpkg -i ../taler-apns-relay*.deb
     92 
     93 If the previous steps succeeded, the ``taler-apns-relay`` command should be found in the $PATH.
     94 
     95 Services, users, groups and file system hierarchy
     96 -------------------------------------------------
     97 
     98 The *taler-apns-relay* package will create several system users
     99 to compartmentalize different parts of the system:
    100 
    101 * ``taler-apns-relay-httpd``: runs the HTTP daemon with the API logic.
    102 * ``taler-apns-relay-worker``: runs the worker daemon interacting with the APNs API.
    103 * ``postgres``: runs the PostgreSQL database (from *postgresql* package).
    104 
    105 The adapter setup uses the following system groups:
    106 
    107 * ``taler-apns-relay-db``: group for all adapter users with direct database access, specifically taler-apns-relay-httpd and taler-apns-relay-worker.
    108 
    109 The package will deploy systemd service files in
    110 ``/usr/lib/systemd/system/`` for the various components:
    111 
    112 * ``taler-apns-relay-httpd.service``: registration REST API.
    113 * ``taler-apns-relay-httpd.socket``: systemd socket activation for the HTTP daemon.
    114 * ``taler-apns-relay-worker.service``: worker daemon interacting with the APNs API.
    115 * ``taler-apns-relay.target``: main target for the relay to be operational.
    116 
    117 The deployment creates the following key locations in the system:
    118 
    119 * ``/etc/taler-apns-relay/``: configuration files.
    120 * ``/run/taler-apns-relay/``: contains the UNIX domain sockets for inter-process communication (IPC).
    121 
    122 Configuration Fundamentals
    123 ==========================
    124 
    125 This chapter provides fundamental details about the adapter configuration.
    126 
    127 The configuration for all adapter components uses a single configuration file
    128 as entry point: ``/etc/taler-apns-relay/taler-apns-relay.conf``.
    129 
    130 System defaults are automatically loaded from files in
    131 ``/usr/share/taler-apns-relay/config.d``.
    132 These default files should never be modified.
    133 
    134 The default configuration ``taler-apns-relay.conf`` configuration file
    135 also includes all configuration files in ``/etc/taler-apns-relay/conf.d``.
    136 The settings from files in
    137 ``conf.d`` are only relevant to particular components of an adapter, while
    138 ``taler-apns-relay.conf`` contains settings that affect all adapter components.
    139 
    140 
    141 The directory ``/etc/taler-apns-relay/secrets`` contains configuration file snippets with
    142 values that should only be readable to certain users.  They are included with the ``@inline-secret@``
    143 directive and should end with ``.secret.conf``.
    144 
    145 To view the entire configuration annotated with the source of each configuration option, you
    146 can use the ``taler-apns-relay config`` helper:
    147 
    148 .. code-block:: shell-session
    149 
    150   # taler-apns-relay -c /etc/taler-apns-relay/taler-apns-relay.conf config dump --diagnostics
    151 
    152 Basic Setup
    153 ===========
    154 
    155 Database setup
    156 --------------
    157 
    158 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default
    159 is:
    160 
    161 .. code-block:: ini
    162   :caption: /etc/taler-apns-relay/secrets/apns-relay-db.secret.conf
    163 
    164   [apns-relaydb-postgres]
    165   config = postgres:///taler-apns-relay
    166 
    167 For a local PostgreSQL installation, the following helper creates the database
    168 and roles, initializes (or upgrades) the schema, and grants service access:
    169 
    170 .. code-block:: console
    171 
    172   # taler-apns-relay-dbconfig
    173 
    174 Worker setup
    175 ------------
    176 
    177 You will need an `Apple private key <https://developer.apple.com/help/account/manage-keys/create-a-private-key/>`_.
    178 Update the configuration files:
    179 
    180 .. code-block:: ini
    181   :caption: /etc/taler-apns-relay/secrets/apns-relay-worker.secret.conf
    182 
    183   [apns-relay-worker]
    184   KEY_ID = 555CFX5XXX
    185   TEAM_ID = GDDDQ9418X
    186   BUNDLE_ID = com.taler-systems.talerwallet
    187 
    188 Copy the private key .p8 file to the configured path ``KEY_FILE`` (``/var/lib/taler-apns-relay/key.p8`` with the default config).
    189 
    190 Make sure this file is accessible to the user running ``taler-apns-relay-worker``, for the default services you should run:
    191 
    192 .. code-block:: console
    193 
    194   $ chown taler-apns-relay-worker:taler-apns-relay-worker /var/lib/taler-apns-relay/key.p8
    195 
    196 And then run the setup process:
    197 
    198 .. code-block:: console
    199 
    200   $ sudo -u taler-apns-relay-worker taler-apns-relay -c /etc/taler-apns-relay/taler-apns-relay.conf setup
    201 
    202 Deployment
    203 ==========
    204 
    205 This chapter describes how to deploy the adapter once the basic installation
    206 and configuration are completed.
    207 
    208 Reverse Proxy Setup
    209 -------------------
    210 
    211 By default, the ``taler-apns-relay-httpd`` service listens for HTTP connections
    212 on a UNIX domain socket.  To make the service publicly available, a reverse
    213 proxy such as nginx should be used.  We strongly recommend to configure nginx
    214 to use TLS.
    215 
    216 The ``taler-apns-relay`` package ships with a sample configuration that can be
    217 enabled in nginx:
    218 
    219 .. code-block:: shell-session
    220 
    221   # vim /etc/nginx/sites-available/taler-apns-relay
    222   < ... customize configuration ... >
    223   # ln -s /etc/nginx/sites-available/taler-apns-relay /etc/nginx/sites-enabled/taler-apns-relay
    224   # systemctl reload nginx
    225 
    226 With this last step, we are finally ready to launch the
    227 main adapter process.
    228 
    229 Launching the relay
    230 -------------------
    231 
    232 .. code-block:: console
    233 
    234   # systemctl enable --now taler-apns-relay.target