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