taler-apns-relay-manual.rst (7453B)
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 2.1, 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 send a background 24 notification to registered devices at a regula interval to wakup 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 You will need the latest version of the rust stable toolchain and a C toolchain: 70 71 .. code-block:: console 72 73 $ sudo apt install rustup build-essential 74 $ rustup toolchain install stable 75 76 Then from top-level run: 77 78 .. code-block:: console 79 80 $ ./bootstrap 81 82 To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services: 83 84 .. code-block:: console 85 86 $ sudo apt install debhelper 87 $ make deb 88 $ sudo dpkg -i ../taler-apns-relay*.deb 89 90 If the previous steps succeeded, the ``taler-apns-relay`` command should be found in the $PATH. 91 92 Services, users, groups and file system hierarchy 93 ------------------------------------------------- 94 95 The *taler-apns-relay* package will create several system users 96 to compartmentalize different parts of the system: 97 98 * ``taler-apns-relay-httpd``: runs the HTTP daemon with the API logic. 99 * ``taler-apns-relay-worker``: runs the worker daemon interacting with the APNs API. 100 * ``postgres``: runs the PostgreSQL database (from *postgresql* package). 101 102 The adapter setup uses the following system groups: 103 104 * ``taler-apns-relay-db``: group for all adapter users with direct database access, specifically taler-apns-relay-httpd and taler-apns-relay-worker. 105 106 The package will deploy systemd service files in 107 ``/usr/lib/systemd/system/`` for the various components: 108 109 * ``taler-apns-relay-httpd.service``: registration REST API. 110 * ``taler-apns-relay-httpd.socket``: systemd socket activation for the HTTP daemon. 111 * ``taler-apns-relay-worker.service``: worker deamon interacting with the APNs API. 112 * ``taler-apns-relay.target``: main target for the relay to be operational. 113 114 The deployment creates the following key locations in the system: 115 116 * ``/etc/taler-apns-relay/``: configuration files. 117 * ``/run/taler-apns-relay/``: contains the UNIX domain sockets for inter-process communication (IPC). 118 119 Configuration Fundamentals 120 ========================== 121 122 This chapter provides fundamental details about the adapter configuration. 123 124 The configuration for all adapter components uses a single configuration file 125 as entry point: ``/etc/taler-apns-relay/taler-apns-relay.conf``. 126 127 System defaults are automatically loaded from files in 128 ``/usr/share/taler-apns-relay/config.d``. 129 These default files should never be modified. 130 131 The default configuration ``taler-apns-relay.conf`` configuration file 132 also includes all configuration files in ``/etc/taler-apns-relay/conf.d``. 133 The settings from files in 134 ``conf.d`` are only relevant to particular components of an adapter, while 135 ``taler-apns-relay.conf`` contains settings that affect all adapter components. 136 137 138 The directory ``/etc/taler-apns-relay/secrets`` contains configuration file snippets with 139 values that should only be readable to certain users. They are included with the ``@inline-secret@`` 140 directive and should end with ``.secret.conf``. 141 142 To view the entire configuration annotated with the source of each configuration option, you 143 can use the ``taler-apns-relay config`` helper: 144 145 .. code-block:: shell-session 146 147 # taler-apns-relay config dump --diagnostics 148 149 Basic Setup 150 =========== 151 152 Database setup 153 -------------- 154 155 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default 156 is: 157 158 .. code-block:: ini 159 :caption: /etc/taler-apns-relay/secrets/apns-relay-db.secret.conf 160 161 [apns-relaydb-postgres] 162 config = postgres:///taler-apns-relay 163 164 If the database is run on a different host, please follow the instructions 165 from the PostgreSQL manual for configuring remote access. 166 167 Assuming the configuration is correct, the following 168 command initializes (or upgrades) the database schema using: 169 You can then use a script to automate a secure database setup: 170 171 .. code-block:: console 172 173 # taler-apns-relay-dbconfig 174 175 Worker setup 176 ------------ 177 178 You will need an `Apple private key <https://developer.apple.com/help/account/manage-keys/create-a-private-key/>`_. 179 Update the configuration files: 180 181 .. code-block:: ini 182 :caption: /etc/taler-apns-relay/secret/apns-relay-worker.secret.conf 183 184 [apns-relay-worker] 185 KEY_ID = 555CFX5XXX 186 TEAM_ID = GDDDQ9418X 187 BUNDLE_ID = com.taler-systems.talerwallet 188 189 Copy the private key .p8 file to the configured path ``KEY_FILE`` (``/var/lib/taler-apns-relay/key.p8`` with the default config). 190 191 Make sure this file is accessible to the user running ``taler-apns-relay-worker``, for the default services you should run: 192 193 .. code-block:: console 194 195 $ chown taler-apns-relay-worker:taler-apns-relay-worker /var/lib/taler-apns-relay/key.p8 196 197 And then run the setup process: 198 199 .. code-block:: console 200 201 $ sudo -u taler-apns-relay-worker taler-apns-relay -c /etc/taler-apns-relay/taler-apns-relay.conf setup 202 203 Deployment 204 ========== 205 206 This chapter describes how to deploy the adapter once the basic installation 207 and configuration are completed. 208 209 Reverse Proxy Setup 210 ------------------- 211 212 By default, the ``taler-apns-relay-httpd`` service listens for HTTP connections 213 on a UNIX domain socket. To make the service publicly available, a reverse 214 proxy such as nginx should be used. We strongly recommend to configure nginx 215 to use TLS. 216 217 The ``taler-apns-relay`` package ships with a sample configuration that can be 218 enabled in nginx: 219 220 .. code-block:: shell-session 221 222 # vim /etc/nginx/sites-available/taler-apns-relay 223 < ... customize configuration ... > 224 # ln -s /etc/nginx/sites-available/taler-apns-relay /etc/nginx/sites-enabled/taler-apns-relay 225 # systemctl reload nginx 226 227 With this last step, we are finally ready to launch the 228 main adapter process. 229 230 Launching the relay 231 ------------------- 232 233 .. code-block:: console 234 235 # systemctl enable --now taler-apns-relay.target