Merge pull request #200 from mwolff44/develop

docs: primary secondary setup

docs/how-to/backup-recovery.en.md

@@ -11,7 +11,7 @@ All the settings are held in one single file `.env` and the configuration in a s
 
 !!! Warning
 
-    If you are not using the default DB, and using MySQL, MariaDB or PostgreSQL, you need to use specific tools for backup and recovery.
+    If you are not using the default DB, PostgreSQL, you need to use specific tools for backup and recovery.
 
 In vast majority of cases, this file and directory can be used to restore a system to a fully working state identical to what was running previously.
 

docs/how-to/backup-recovery.fr.md

@@ -11,7 +11,7 @@ Tous les paramètres sont conservés dans un seul fichier `.env` et la configura
 
 !!! Warning
 
-    Si vous n'utilisez pas la base de données par défaut, et que vous utilisez MySQL, MariaDB ou PostgreSQL, vous devez utiliser des outils spécifiques pour la sauvegarde et la restauration.
+    Si vous n'utilisez pas la base de données par défaut, PostgreSQL, vous devez utiliser des outils spécifiques pour la sauvegarde et la restauration.
 
 Dans la grande majorité des cas, ce fichier et ce répertoire peuvent être utilisés pour restaurer un système dans un état de fonctionnement identique à ce qui fonctionnait auparavant.
 

docs/how-to/pks-standby-failover.en.md

@@ -0,0 +1,183 @@
+<!---
+# P-KISS-SBC documentation © 2007-2024 by Mathias WOLFF 
+# is licensed under Attribution-NonCommercial-ShareAlike 4.0 International (see https://creativecommons.org/licenses/by-nc-sa/4.0/)
+# SPDX-License-Identifier: CC-BY-NC-SA-4.0
+--->
+
+# PKS Standby failover setup
+
+PKS can be deployed in passive active mode, to enable recovery in the event of a major incident.
+In this configuration, data will be synchronized from the primary server to the secondary server. Note that in the configuration presented on this page, the secondary database is not writable.
+
+## Prerequisites
+
+You need to deploy 2 complete instances of PKS following the standard process.
+
+## Implementation
+
+The planned IP ports of the primary-secondary DB are as follows as an example :
+
+* Primary DB: 10.0.3.10:5432
+* Secondary DB: 10.0.3.11:5432
+
+## Primary server preparation
+
+!!! Warning
+
+    The DB must be started !
+
+Create a special account for primary-secondary stream replication :
+
+    # 1. Enter the container
+    docker exec -it pks-db bash
+
+    # 2. Connect to PostgreSQL
+    psql -U postgres
+
+    # 3. Create user rules
+    CREATE ROLE repuser WITH LOGIN REPLICATION CONNECTION LIMIT 5 PASSWORD '123456';
+    # Username repuser; Maximum number of links: 5; Password: 123456
+
+    # 4. View rules
+    \du
+
+                                       List of roles
+     Role name |                         Attributes                         | Member of
+    -----------+------------------------------------------------------------+-----------
+     postgres  | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
+     repuser   | Replication                                               +| {}
+               | 5 connections                                              |
+
+    # 5. Exit
+    \q
+    exit
+
+Modify the primary configuration file
+
+    # 1. Enter the folder of the primary server
+    cd /srv/pks/db
+
+    # 2. Add rules at the end
+    echo "host replication repuser 10.0.3.11/24 md5" >> pg_hba.conf
+
+Modify the postgresql.conf configuration file, find the following lines, uncomment and modify the configuration:
+
+    archive_mode = on				# Enable Archive Mode
+    archive_command = '/bin/date'	# Set archiving behavior
+    # The sum of the number of concurrent connections from the slave to the host
+    max_wal_senders = 10			
+    # Specifies that if the backup server needs to obtain log segment files for stream replication, pg_ The minimum size of past log file segments that can be retained in the wal directory	
+    wal_keep_size = 16		
+    # Specify a list of backup servers that support synchronous replication
+    synchronous_standby_names = '*'
+
+For more details of parameters, please refer to: https://www.postgresql.org/docs/
+
+Restart the primary container
+
+    #Using pg_ctl stop stops the database safely
+    docker exec -it -u postgres pks-db pg_ctl stop
+    docker start pks-db
+
+## Secondary server configuration
+
+Edit the docker compose configuration :
+
+    # Create repl directory
+    mkdir /srv/pks/repl
+    chmod 777 /srv/pks/repl
+
+    # Stop pks
+    pks stop
+
+    # line 92 add :
+    - pks-db-repl:/var/lib/postgresql/repl
+
+    # line 180 add :
+    pks-db-repl:
+        driver: local
+        driver_opts:
+        type: 'none'
+        o: 'bind'
+        device: '/srv/pks/repl'
+
+    # And start pks
+    pks start
+
+Synchronize data
+
+    # 1. Enter the container
+    docker exec -it -u postgres pks-db bash
+
+    # 2. Back up the host data to the repl folder. Here, enter the password set above: 123456
+    pg_basebackup -R -D /var/lib/postgresql/repl -Fp -Xs -v -P -h 10.0.3.11 -p 5432 -U repuser
+
+    pg_basebackup: initiating base backup, waiting for checkpoint to complete
+    pg_basebackup: checkpoint completed
+    pg_basebackup: write-ahead log start point: 0/2000028 on timeline 1
+    pg_basebackup: starting background WAL receiver
+    pg_basebackup: created temporary replication slot "pg_basebackup_154"
+    24264/24264 kB (100%), 1/1 tablespace
+    pg_basebackup: write-ahead log end point: 0/2000138
+    pg_basebackup: waiting for background process to finish streaming ...
+    pg_basebackup: syncing data to disk ...
+    pg_basebackup: renaming backup_manifest.tmp to backup_manifest
+    pg_basebackup: base backup completed
+
+    # 3. Exit the container after the backup is completed
+    exit
+
+Rebuild the secondary container
+
+Through the initial backup in the previous step, you can now rebuild the secondary container using the data in /srv/pks/repl. First delete the db directory, and then change the repl directory to db, which is the data directory of the secondary DB:
+
+    # 1. Delete container
+    docker rm -f pks-db
+
+    # 2. Delete the original folder and rename repl to db
+    cd /srv/pks/
+    rm -rf db
+    mv repl db
+    cd /srv/pks/db
+
+    # 3. View configuration information
+    # postgresql.auto.conf will contain the information required for replication
+    cat postgresql.auto.conf
+
+    primary_conninfo = 'user=repuser password=123456 channel_binding=prefer host=10.0.3.11 port=5432 sslmode=prefer sslcompression=0 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres target_session_attrs=any'
+
+Rebuild the secondary container:
+
+    # Remove the settings in docker compose file
+
+    # Restart the DB container
+    pks start
+
+## View primary-secondary replication information
+
+    ps -aux | grep postgres
+
+    Main library process:
+    postgres: walsender repuser 172.18.0.1(52678) streaming 0/3000148
+     Process from library:
+    postgres: walreceiver streaming 0/3000148
+
+Verify primary-secondary configuration
+
+    # Enter the primary container and switch to the postgres user
+    docker exec -it pks-db bash
+    psql -U postgres
+
+    -- Query replication information
+    select * from pg_stat_replication;
+
+    pid | usesysid | usename | application_name | client_addr | client_hostname...
+    170	16384	repuser	walreceiver	172.18.0.1		52678	2021-09-29 05:57:30.471391+00...
+
+## How to manage
+
+You can force SIP requests to one of the 2 servers.
+
+The secondary server's database is read-only, allowing SBC operation but not modification.
+
+If you want to force SIP traffic on one server, simply switch off the SIP proxy container: `docker start pks-sip`

docs/how-to/pks-standby-failover.fr.md

@@ -0,0 +1,183 @@
+<!---
+# P-KISS-SBC documentation © 2007-2024 by Mathias WOLFF 
+# is licensed under Attribution-NonCommercial-ShareAlike 4.0 International (see https://creativecommons.org/licenses/by-nc-sa/4.0/)
+# SPDX-License-Identifier: CC-BY-NC-SA-4.0
+--->
+
+# PKS Standby failover architecture
+
+PKS peut-être déployé en mode actif passif, afin de permettre une reprise en cas d'incident majeur.
+Dans cette configuration, les données seront synchronisées du serveur primaire vers le serveur secondaire. A noter que dans la configuration présentée dans cette page, la base secondaire n'est pas accessible en écriture.
+
+## Pré-requis
+
+Vous devez déployer 2 instances complètes de PKS en suivant le process standard.
+
+## Mise en oeuvre
+
+Les ports IP prévus pour la base de données primaire-secondaire sont, par exemple, les suivants :
+
+* Primary DB: 10.0.3.10:5432
+* Secondary DB: 10.0.3.11:5432
+
+## Préparation du server primaire
+
+!!! Warning
+
+    La DB doit-être redémarrée !
+
+Créer un compte spécial pour les flux de réplication primary-secondary :
+
+    # 1. Entrer dans le container
+    docker exec -it pks-db bash
+
+    # 2. Se connecter à PostgreSQL
+    psql -U postgres
+
+    # 3. Créer le rôle utilisateur
+    CREATE ROLE repuser WITH LOGIN REPLICATION CONNECTION LIMIT 5 PASSWORD '123456';
+    # Username repuser; Maximum number of links: 5; Password: 123456
+
+    # 4. Voir les rôles
+    \du
+
+                                       List of roles
+     Role name |                         Attributes                         | Member of
+    -----------+------------------------------------------------------------+-----------
+     postgres  | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
+     repuser   | Replication                                               +| {}
+               | 5 connections                                              |
+
+    # 5. Quitter
+    \q
+    exit
+
+Modifier le fichier de configuration du primaire :
+
+    # 1. Entrer dans le dossier du serveur primaire 
+    cd /srv/pks/db
+
+    # 2. Et ajouter la règle à la fin
+    echo "host replication repuser 10.0.3.11/24 md5" >> pg_hba.conf
+
+Modifier le fichier postgresql.conf , en trouvant les lignes suivantes, en décommentant et en modifiant ainsi:
+
+    archive_mode = on				# Enable Archive Mode
+    archive_command = '/bin/date'	# Set archiving behavior
+    # The sum of the number of concurrent connections from the slave to the host
+    max_wal_senders = 10			
+    # Specifies that if the backup server needs to obtain log segment files for stream replication, pg_ The minimum size of past log file segments that can be retained in the wal directory	
+    wal_keep_size = 16		
+    # Specify a list of backup servers that support synchronous replication
+    synchronous_standby_names = '*'
+
+Pour plus de détails sur les paramètres, veuillez vous référer à : https://www.postgresql.org/docs/
+
+Redémarrer le container primaire :
+
+    #Using pg_ctl stop stops the database safely
+    docker exec -it -u postgres pks-db pg_ctl stop
+    docker start pks-db
+
+## Configuration du serveur secondaire
+
+Editer la configuration de docker compose :
+
+    # Créer le dossier repl 
+    mkdir /srv/pks/repl
+    chmod 777 /srv/pks/repl
+
+    # Stop pks
+    pks stop
+
+    # line 92 add :
+    - pks-db-repl:/var/lib/postgresql/repl
+
+    # line 180 add :
+    pks-db-repl:
+        driver: local
+        driver_opts:
+        type: 'none'
+        o: 'bind'
+        device: '/srv/pks/repl'
+
+    # Et démarrer pks
+    pks start
+
+Synchronizer les donner
+
+    # 1. Entrer dans le container
+    docker exec -it -u postgres pks-db bash
+
+    # 2. Sauvegardez les données de l'hôte dans le dossier repl. Saisissez ici le mot de passe défini ci-dessus : 123456
+    pg_basebackup -R -D /var/lib/postgresql/repl -Fp -Xs -v -P -h 10.0.3.11 -p 5432 -U repuser
+
+    pg_basebackup: initiating base backup, waiting for checkpoint to complete
+    pg_basebackup: checkpoint completed
+    pg_basebackup: write-ahead log start point: 0/2000028 on timeline 1
+    pg_basebackup: starting background WAL receiver
+    pg_basebackup: created temporary replication slot "pg_basebackup_154"
+    24264/24264 kB (100%), 1/1 tablespace
+    pg_basebackup: write-ahead log end point: 0/2000138
+    pg_basebackup: waiting for background process to finish streaming ...
+    pg_basebackup: syncing data to disk ...
+    pg_basebackup: renaming backup_manifest.tmp to backup_manifest
+    pg_basebackup: base backup completed
+
+    # 3. Sortir du container après que la sauvegarde soit terminée
+    exit
+
+Reconstruire le container secondaire
+
+Grâce à la sauvegarde initiale de l'étape précédente, vous pouvez maintenant reconstruire le conteneur secondaire en utilisant les données contenues dans /srv/pks/repl. Supprimez d'abord le répertoire db, puis remplacez le répertoire repl par db, qui est le répertoire de données de la base de données secondaire :
+
+    # 1. Supprimer le container
+    docker rm -f pks-db
+
+    # 2. Supprimer le dossier de base et renommer repl en db
+    cd /srv/pks/
+    rm -rf db
+    mv repl db
+    cd /srv/pks/db
+
+    # 3. Voir les informations de configuration
+    # postgresql.auto.conf contiendra les informations nécessaires à la réplication
+    cat postgresql.auto.conf
+
+    primary_conninfo = 'user=repuser password=123456 channel_binding=prefer host=10.0.3.11 port=5432 sslmode=prefer sslcompression=0 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres target_session_attrs=any'
+
+Reconstruire le container secondaire:
+
+    # Supprimer les paramètres ajouté plus haut dans le fichier du docker compose
+
+    # Redémarrer le container DB
+    pks start
+
+## Visualiser les informations de réplication primaire-secondaire
+
+    ps -aux | grep postgres
+
+    Main library process:
+    postgres: walsender repuser 172.18.0.1(52678) streaming 0/3000148
+     Process from library:
+    postgres: walreceiver streaming 0/3000148
+
+Visualiser les informations de réplication
+
+    # Entrer dans le container primaire et basculer en utilisateur postgres
+    docker exec -it pks-db bash
+    psql -U postgres
+
+    -- Query replication information
+    select * from pg_stat_replication;
+
+    pid | usesysid | usename | application_name | client_addr | client_hostname...
+    170	16384	repuser	walreceiver	172.18.0.1		52678	2021-09-29 05:57:30.471391+00...
+
+## Gestion
+
+Vous pouvez forcer les requêtes SIP sur l'un des 2 serveurs.
+
+La base de données du serveur secondaire est uniquement en lecture seule, permettant un fonctionnement du SBC mais ne permettant pas d'effectuer de modification.
+
+Si vous voulez forcer le trafic SIP sur un serveur, il suffit d'éteindre le container du proxy SIP : `docker start pks-sip`

jampack.config.mjs

@@ -0,0 +1,3 @@
+export default {
+    nocache: true,
+  };