regional-automated-manual.rst (11459B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2024 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 Florian Dold 17 @author Marcello Stanisci 18 @author Christian Grothoff 19 20 21 .. target audience: operator 22 23 Regional Currency Automated Setup Manual 24 ######################################## 25 26 This manual describes how to setup a regional currency using a script that largely automates the process. If you want to do a custom setup you can follow the :doc:`custom setup manual<regional-custom-manual>`. 27 28 29 .. contents:: Table of Contents 30 :local: 31 32 .. include:: ../frags/regional-manual-architecture.rst 33 34 Guided Automated Setup 35 ====================== 36 37 Prerequisites 38 +++++++++++++ 39 40 For this manual, we assume that the system is deployed on a contemporary 41 Debian GNU/Linux Bookworm or Ubuntu Mantic system using the binary packages provided. 42 Furthermore, you should run the process on a system with one or more globally 43 reachable IP address(es) *and* with various DNS names already pointing to 44 these IPs. 45 46 Preparing the required subdomain names 47 ++++++++++++++++++++++++++++++++++++++ 48 49 The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component. 50 These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name, 51 where you can create type (A) entries, as subdomains pointing to your own server public IP address. 52 A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is 53 to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly. 54 55 Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have 56 propagated over the Internet correctly, and they are currently publicly available. 57 58 You can check this from your terminal very easily with the "ping" command, as this: 59 60 .. code-block:: console 61 62 $ ping -c1 bank.$DOMAIN_NAME 63 $ ping -c1 exchange.$DOMAIN_NAME 64 $ ping -c1 backend.$DOMAIN_NAME 65 66 You can also use `this tool <https://toolbox.googleapps.com/apps/dig/>`_ for the same purpose, and to check the propagation status. 67 68 .. warning:: 69 Take into account some hosting providers providing virtualized servers (VPS or VDS) can enable by default the firewall program "UFW", blocking by default the port number 443. So you have to either disable this firewall program, or open to this 443 port number to allow https. 70 71 Now you are ready to go with the next step. 72 73 Obtaining the Scripts 74 +++++++++++++++++++++ 75 76 First, download the deployment scripts via Git: 77 78 .. code-block:: console 79 80 # apt update && apt install git 81 $ git clone git://git.taler.net/taler-deployment 82 83 Running the Guided Configuration 84 ++++++++++++++++++++++++++++++++ 85 86 Navigate into the *regional-currency/* directory and run *main.sh* as **root**: 87 88 .. code-block:: console 89 90 $ cd taler-deployment/regional-currency/ 91 # ./main.sh 92 93 The script will start by installing the required packages and then asking you fundamental questions about the desired setup, in particular: 94 95 #. Wether to encrypt, when stored on disk, sensible configurations such as the admin password. 96 #. The name of the regional currency. It must have 3 to 11 letters. 97 #. Whether to setup the regional currency to be backed by a fiat currency. You'll need a bank account at a fiat currency bank offering an online banking protocol supported by LibEuFin Nexus. If you answer ``y``, you will also need to provide the following information: 98 99 #. The ISO code of the fiat currency. Use 'CHF' or 'EUR'. 100 #. The IBAN of the fiat bank account. 101 #. The BIC of the fiat bank account. 102 #. The legal name of the fiat bank account. 103 104 #. The name of the regional currency bank. It will be shown to business users when they interact with the system. 105 #. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN_NAME``, ``exchange.$DOMAIN_NAME`` and ``backend.$DOMAIN_NAME``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer). 106 #. Whether to use TLS or not. You should answer ``y`` in most cases. 107 #. Whether to setup SMS two-factor authentication using `Telesign <https://www.telesign.com>`_, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires `a Customer ID and an API Key <https://developer.telesign.com/enterprise/docs/authentication#basic-authentication>`_. You should answer ``y`` in most cases. 108 #. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably using the autogenerated one. 109 #. Whether to generate terms of service (ToS) for the exchange from default templates. 110 #. Whether to generate a privacy policy for the exchange from default templates. 111 112 The information you entered as well as the generated bank admin password will 113 be stored in a file called ``config/user.conf``. If you run the script in 114 the future again (for example, to upgrade the installation), you will not be asked 115 these questions a second time. 116 117 After answering all of the questions, the actual installation will start. The 118 scripts will download and configure various packages, which may take some time. 119 Grab a coffee. 120 121 .. note:: 122 123 At this point, the setup is NOT connected to any fiat bank account! The next 124 steps must always be done manually! 125 126 Running the script again from scratch 127 +++++++++++++++++++++++++++++++++++++ 128 129 If for some reason your installation doesn't work because you have answered erroneously 130 some of the interactive questions, or you just want to reset the current installation and to re-deploy 131 the script again for having its latest changes, you will have to proceed as follows: 132 133 In brief, you need to wipe completely the "content" of the file config/user.conf, this doesn't mean 134 to remove the file itself, but only its content. Even though you can do this manually by editing the file manually 135 with your preferred text editor, you can also do this in one single command. 136 137 .. code-block:: console 138 139 # rm config/user.conf 140 141 .. note:: 142 143 In future versions of the program when executed for the second time, the program itself will 144 show an option to offer wiping the content of this config/user.conf file, automatically. 145 146 Multi-factor authentication 147 +++++++++++++++++++++++++++ 148 149 The script allows you to configure multi-factor authentication via SMS using Telesign as a provider. You can also configure multi-factor authentication via email or use providers other than Telesign for SMS. You will need to configure these channels manually as described in :ref:`multi-factor authentication <libeufin-mfa>`. 150 151 If you choose not to back your regional currency with a fiat currency, you can stop here. 152 153 Web-based Configuration 154 +++++++++++++++++++++++ 155 156 By default, the regional currency conversion rates are 1:1. You can change the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. 157 158 Connecting to a Fiat Bank: the EBICS setup 159 ++++++++++++++++++++++++++++++++++++++++++ 160 161 To complete the conversion setup, you have to set up an EBICS subscriber using the fiat bank account you specified during the automated setup. 162 163 When you sign up for an EBICS-enabled bank account, the bank will provide you 164 with various credentials. Those must be provided in the 165 ``/etc/libeufin/libeufin-nexus.conf`` configuration file. 166 167 .. note:: 168 As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history. 169 If this is not possible, use the ``IGNORE_TRANSACTIONS_BEFORE`` configuration to ignore old transactions. 170 171 The following snippet shows the mandatory configuration values: 172 173 .. _core-config: 174 175 .. code-block:: ini 176 177 [nexus-ebics] 178 # Bank 179 HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx 180 BANK_DIALECT = postfinance 181 182 # EBICS IDs 183 HOST_ID = PFEBICS 184 USER_ID = PFC00563 185 PARTNER_ID = PFC00563 186 187 .. warning:: 188 This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. 189 190 Reuse existing client keys 191 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 192 193 If you have client keys from a previous EBICS setup you can copy the JSON file to ``/var/lib/libeufin-nexus/client-ebics-keys.json``. 194 195 Make sure this file is accessible to the user running ``libeufin-nexus``, you should run: 196 197 .. code-block:: console 198 199 $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json 200 201 Create new client keys 202 ^^^^^^^^^^^^^^^^^^^^^^ 203 204 Run the following command to start the EBICS setup process: 205 206 .. code-block:: console 207 208 $ sudo -u libeufin-nexus libeufin-nexus ebics-setup 209 210 If the previous command failed when running EBICS INI with an error code of 211 ``EBICS_INVALID_USER_OR_USER_STATE``, you need to confirm your keys to your bank to 212 activate your account. 213 214 To that end, the previous run should have left a PDF document that you can 215 print, sign and send to the bank. Look for the message that looks like ``PDF 216 file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. 217 218 Once the bank has received and processed this document you can continue. 219 220 Get bank keys 221 ^^^^^^^^^^^^^ 222 223 Run the following command to finish the EBICS setup process: 224 225 .. code-block:: console 226 227 $ sudo -u libeufin-nexus libeufin-nexus ebics-setup 228 229 The EBICS setup is finished once the bank keys have been accepted. 230 231 232 Configuring the Exchange for Conversion 233 +++++++++++++++++++++++++++++++++++++++ 234 235 In our automated setup the second account is automatically set up correctly 236 without fees or special restrictions. However, various additional 237 *restrictions* and *options* could be configured. Details are explained in 238 the :ref:`regional conversion setup <regional-conversion-setup>` section for the 239 manual setup and in the the manpage of ``taler-exchange-offline``. 240 241 242 .. include:: ../frags/regional-system-on.rst 243 .. include:: ../frags/deploying-tos.rst 244 245 246 Installing Updates 247 ++++++++++++++++++ 248 249 The standard procedure for installing updates is to: 250 251 * First, make a backup (!) 252 * Stop Taler services 253 * Install new version 254 * Upgrade databases 255 * Start Taler services 256 257 The "upgrade.sh" script in the "regional-currency/" folder of "deployment.git" 258 shows how to do the above steps *except* for the backup. For the backup, all 259 critical bits of data will be in the Postgresql databases. Thus, we recommend 260 following the database manual on making backups.