commit 6ad0e19fc0417f7ec55063b1d883fe999c18d953
parent dd6fcf5afbc9bfd0e21a6a1081364f610cd5bc0b
Author: Javier Sepulveda <javier.sepulveda@uv.es>
Date: Fri, 17 May 2024 12:40:31 +0200
New system administration section for documentation and tutorials
Diffstat:
11 files changed, 160 insertions(+), 0 deletions(-)
diff --git a/images/grafana-postgres-exporter.png b/images/grafana-postgres-exporter.png
Binary files differ.
diff --git a/images/kuma.png b/images/kuma.png
Binary files differ.
diff --git a/images/regional-arch.png b/images/regional-arch.png
Binary files differ.
diff --git a/images/taler-monitoring-infrastructure.png b/images/taler-monitoring-infrastructure.png
Binary files differ.
diff --git a/images/uptime-kuma-edit.png b/images/uptime-kuma-edit.png
Binary files differ.
diff --git a/images/uptime-kuma-from-grafana.png b/images/uptime-kuma-from-grafana.png
Binary files differ.
diff --git a/index.rst b/index.rst
@@ -18,6 +18,7 @@
@author Sree Harsha Totakura
@author Marcello Stanisci
@author Christian Grothoff
+ @author Javier Sepulveda
GNU Taler Documentation
=======================
@@ -63,6 +64,7 @@ Documentation Overview
taler-auditor-manual
taler-developer-manual
libeufin/index
+ system-administration/index
design-documents/index
global-licensing
manindex
diff --git a/system-administration/images/lego-logo.svg b/system-administration/images/lego-logo.svg
@@ -0,0 +1 @@
+<svg width="538.167" height="152.232" viewBox="0 0 142.39 40.278" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><g fill="none" stroke="#00add8" stroke-width="2.646"><path d="M129.04 6.615c-6.952 0-6.952 4.973-6.952 6.024V27.61c0 .62 0 6.053 6.952 6.053s6.735-5.423 6.735-6.053V12.64c0-1.013.217-6.024-6.735-6.024z"/><path d="M113.61 12.639c0-1.013.217-6.025-6.735-6.025s-6.952 4.973-6.952 6.025V27.61c0 .62 0 6.053 6.952 6.053s6.735-5.423 6.735-6.053v-7.465h-4.53" stroke-linecap="square"/></g><g fill="none" stroke="#00add8" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.323"><path d="M88.866 31.356v-3.374c0-1.472-.874-2.83-2.724-2.83H81.05m5.509 8.511a2.307 2.307 0 1 0 4.614 0 2.307 2.307 0 0 0-4.614 0zM86.559 20.145h-5.551m5.551 0a2.307 2.307 0 1 0 4.614 0 2.307 2.307 0 0 0-4.614 0zM88.866 8.922v3.374c0 1.472-.874 2.83-2.724 2.83H81.05m5.509-8.511a2.307 2.307 0 1 0 4.614 0 2.307 2.307 0 0 0-4.614 0z"/></g><path d="M62.737 13.728V9.291c-.001-3.22 2.772-5.887 5.993-5.889 3.221-.002 5.997 2.662 6 5.883.002 3.22 0 4.443 0 4.443" fill="none" stroke="#4db969" stroke-linecap="round" stroke-linejoin="round" stroke-width="2.133" style="paint-order:fill markers stroke"/><rect x="60.158" y="13.728" width="17.047" height="12.13" ry="1.725" fill="#4db969" stroke="#4db969" stroke-linecap="round" stroke-linejoin="round" stroke-width="2.117" style="paint-order:normal"/><g fill="#fff" stroke-width=".146"><path class="cls-4" d="M66.397 21.903a.414.414 0 0 0 .358-.206l.358-.62.285-.494.015-.025.906-1.571a.414.414 0 0 1 .717 0l.61 1.055a.412.412 0 1 0 .716-.412l-1.326-2.297a.414.414 0 0 0-.717 0l-2.28 3.947a.414.414 0 0 0 .358.623z"/><path class="cls-4" d="M73.172 22.73h-8.207a.414.414 0 0 1-.358-.62l3.713-6.432a.414.414 0 0 1 .716 0l2.759 4.774a.414.414 0 0 1-.358.62h-3.129a.412.412 0 1 0 0 .826h4.563a.414.414 0 0 0 .358-.62l-3.865-6.695a.414.414 0 0 0-.358-.208h-.652a.414.414 0 0 0-.359.208l-4.492 7.781a.411.411 0 0 0 0 .414l.326.564a.41.41 0 0 0 .357.207h8.987a.41.41 0 0 0 .357-.207.412.412 0 0 0-.358-.612zM73.226 19.629l.868 1.503a.412.412 0 1 0 .715-.414l-.868-1.501a.414.414 0 0 0-.715.412zM70.555 15.003l.284.491a.412.412 0 1 0 .715-.412l-.283-.49a.414.414 0 0 0-.716.411zM71.793 17.147l.478.829a.414.414 0 0 0 .716-.414l-.478-.829a.414.414 0 0 0-.716.414zM72.217 24.384h-.981a.414.414 0 0 0 0 .827h.98a.412.412 0 0 0 .357-.62.413.413 0 0 0-.356-.207zM69.327 24.384a.414.414 0 1 0 .001.828.414.414 0 0 0-.001-.828zM65.564 17.146l1.237-2.143a.414.414 0 0 0-.717-.412l-1.236 2.141a.414.414 0 1 0 .716.414zM63.269 21.132l1.346-2.332a.412.412 0 1 0-.715-.414l-1.346 2.332a.412.412 0 1 0 .715.414zM67.418 24.384h-2.28a.414.414 0 0 0 .002.827h2.278a.415.415 0 0 0 .358-.62.415.415 0 0 0-.358-.207z"/></g><g fill="none" stroke="#f9a11d" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.323"><path d="M48.523 31.356v-3.374c0-1.472.874-2.83 2.724-2.83h5.092m-5.509 8.511a2.307 2.307 0 1 1-4.614 0 2.307 2.307 0 0 1 4.614 0zM50.83 20.145h5.551m-5.551 0a2.307 2.307 0 1 1-4.614 0 2.307 2.307 0 0 1 4.614 0zM48.523 8.922v3.374c0 1.472.874 2.83 2.724 2.83h5.092M50.83 6.614a2.307 2.307 0 1 1-4.614 0 2.307 2.307 0 0 1 4.614 0z"/></g><g fill="none" stroke="#f9a11d" stroke-linecap="square"><path d="M34.821 20.145H24.104m13.285 13.518H24.104V6.614h13.285" stroke-width="2.646"/><path d="M6.615 33.663h10.9M6.615 6.614v27.049m0-27.049v27.049" stroke-width="2.381"/></g></svg>
diff --git a/system-administration/index.rst b/system-administration/index.rst
@@ -0,0 +1,26 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2023 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 Javier Sepulveda
+
+System Administration tutorials
+##################################
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ lego-certificates
+ taler-monitoring-infrastructure
diff --git a/system-administration/lego-certificates.rst b/system-administration/lego-certificates.rst
@@ -0,0 +1,131 @@
+.. image:: images/lego-logo.svg
+ :width: 300
+ :height: 150
+ :alt: lego logo
+
+What is Lego
+###############
+
+Let's Encrypt client and ACME library written in Go.
+
+* You can request new certificates
+* You can request new subdomain alt names for your current main certicate
+* You can renew certificates
+* You can revoke certificates
+* You can request certificates by using dynamic DNS (API access, with multiple providers)
+
+
+Why lego is better for managing certificates
+===============================================
+
+* The process is not considered a live process, so in case something goes wrong your websites won't break.
+* You can hook some actions after the renewal process, such as reloading Dovecot.
+* The process of either obtaining or renewing new certicates, doesn't require you to stop NGINX.
+* Lego just helps you to obtain the certificates as text files, which you can copy afterwards to the right locations to be used by NGINX.
+
+
+Requirements
+=============
+- A fully automation of installing and deploying Lego can be found in migration-exercise-stable.git/taler.net/lego-certificates
+- If you want to do things manually instead, you can execute the "install-lego.sh" file.
+- To use our script simply execute the "main-certs.sh" file, which not only will install lego on your system, but
+ will try to obtain certificates for the ones listed on the "domains" text file.
+- Lego can work with so many domain providers (dynamic DNS), so please make sure you have indicated the right
+ API credentials on the "envars" variables file for your domain provider. In our specific case, we use Joker.
+- Make sure either you are not using UFW or any firewall program, or that if you are using one, make sure you have opened beforehand
+ the port 80.
+
+Installation and deployment with a script
+#############################################
+
+#. Git clone migration-exercise-stable.git
+#. Navigate to the folder taler.net/lego-certificates
+#. Add your desired FQDNs in the "domains" text file
+#. Execute the "main-certs.sh" file as ./main-certs.sh
+
+Manually installing Lego
+===========================
+
+.. note ::
+ Just as an informative process, as this is fully automated by executing either the "install-lego.sh" or the "main-certs.sh" files.
+
+.. code-block:: console
+
+ $ wget https://github.com/go-acme/lego/releases/download/v4.16.1/lego_v4.16.1_linux_amd64.tar.gz
+ $ tar -axf lego_v4.16.1_linux_amd64.tar.gz
+ $ # If moving directly to /usr/local/bin, just copy the lego binary file to /usr/local/bin
+ $ cp /tmp/lego /usr/local/bin/
+ $ # If copying the binary to /opt/lego, make symbolic links to /usr/local/bin
+ $ cp /tmp/lego /opt/lego/
+ $ ln -s /usr/local/bin /opt/lego/lego
+
+Full documentation on how to use Lego can be found in: https://go-acme.github.io/lego/
+
+Usage of lego once it has been installed
+###############################################
+
+* Each time you want to add an additional domain to your setup, just add the FQDN to the "domains" text file
+* There is nothing else to do in your side now, the server itself will trigger automatically (systemd timer) the "renew-certs.service"
+* We have implemented the use of lego with systemd timers, so there is not additional maintenance
+
+Automatic renewal of certificates
+##################################
+
+We use systemd timers do undertake this.
+
+.. note ::
+ To check the systemd timer is running properly and "waiting", you can execute "systemctl status renew-certs.timer"
+
+More information: https://go-acme.github.io/lego/usage/cli/renew-a-certificate/
+
+
+Email notifications
+====================
+
+* Let's encrypt notifications will arrive to your configured email address.
+* You can specify your email address by editing the "envars" text file (variable "LEGO_ACCOUNT_EMAIL").
+* On each successful renewal, you will receive an email notification from the script.
+
+Additional information for troubleshooting
+###############################################
+
+Once you have the certificate generated files (/root/.lego/xxx.crt, /root/.lego/xxx.key)
+they will be copied to /etc/ssl/certs and /etc/ssl/private, respectively.
+
+How to configure NGINX to use your certificates
+##################################################
+
+In the NGINX virtualhost configuration file just include "include conf.d/talerssl.conf;" line, and
+make sure you have a file named "talerssl.conf" in the path: /etc/nginx/conf.d with the next content:
+
+.. code-block:: console
+
+ $ # Taler SSL defaults
+ $ # We're using one certificate with taler.net as primary name
+ $ # and everything else as alt name.
+ $ # These 2 next lines are the important ones, which refer to the certificates file (.crt), and its private key (.key)
+ $ ssl_certificate /etc/ssl/certs/taler.net.crt;
+ $ ssl_certificate_key /etc/ssl/private/taler.net.key;
+ $ ssl_session_cache shared:SSL:10m;
+ $ ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
+ $ add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
+
+
+Presence of Lego in our servers
+######################################
+
+* TUE - University of Eindhoven
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/taler-monitoring-infrastructure.rst b/system-administration/taler-monitoring-infrastructure.rst
