Updates for Virtual Appliance 2.9.0 (#110)

docs/10-certificate-key/03-installation-guide/04-deployment/06-deployment-appliance/01-overview.md

@@ -30,7 +30,7 @@ Because of different availability and public/private access to containers, the v
 By *minimum* requirements we mean resources which needed for CZERTAINLY and kubernetes installation and for basic evaluation of its features.
 
 :::tip Resource management
-Resources can be scaled up or down based on the needs of the platform. The resources needed for the CZERTAINLY platform differs based on the number of managed objects, implemented use-cases, and required connectors. 
+Resources can be scaled up or down based on the needs of the platform. The resources needed for the CZERTAINLY platform differs based on the number of managed objects, implemented use-cases, and required connectors.
 :::
 
 ## Download and import image

docs/10-certificate-key/03-installation-guide/04-deployment/06-deployment-appliance/03-initialization.md

@@ -67,6 +67,10 @@ To enter obtained credentials, use option **Main Menu -> [Configure Docker repos
 
 Option **[Configure CZERTAINLY](./TUI/main-menu#configure-czertainly)** of the main menu opens dialog where you can choose version of CZERTAINLY and it's components you want to install.
 
+:::info Note
+If you are not planning to use email notifications, disable *email Provider*. It is by default enabled and when not configured properly, installation will hang.
+:::
+
 ## Install CZERTAINLY
 
 When you select **[Install CZERTAINLY](./TUI/main-menu#install-czertainly)** from the main menu. The installation will begin after confirmation.

docs/10-certificate-key/03-installation-guide/04-deployment/06-deployment-appliance/04-TUI/03-main-menu.md

@@ -8,9 +8,11 @@ Main menu allows to select and execute basic tasks on CZERTAINLY appliance, it o
 | **n**etwork     | [Configure HTTP proxy](#configure-http-proxy)                                   | If your network policy requires using HTTP proxy you can configure it under this option. |
 | **i**ngressTLS  | [Configure ingress TLS certificates](#configure-ingress-tls-certificates)       | Custom HTTPS certificates for CZERTAINLY web interface can be configured here.           |
 | **t**rustedCA   | [Configure custom trusted certificates](#configure-custom-trusted-certificates) | Use this option to change default list of trusted certificates of CZERTAINLY.            |
-| **p**ostrgres   | [Configure database](#configure-database)                                       | You can change default configuration of postgres database with this option.              |
+| **p**ostgres    | [Configure database](#configure-database)                                       | You can change default configuration of postgres database with this option.              |
 | **d**ockerRepo  | [Configure Docker repository access credentials](#configure-docker-repository-access-credentials) | Configure credentials for Licensed parts of CZERTAINLY here.           |
+| **m**ail        | [Configure email server parameters](#configure-email-server-parameters)         | Parameters of email server are needed for sending notifications.                         |
 | **c**zertainly  | [Configure CZERTAINLY](#configure-czertainly)                                   | Use this option to select version and components of CZERTAINLY to install.               |
+| **i**nstall     | [Install CZERTAINLY](#install-czertainly)                                       | Execute CZERTAINLY installation.                                                         |
 | **s**tatus      | [Show CZERTAINLY status](#show-czertainly-status)                               | This option will show status of CZERTAINLY and Kubernetes subsystem.                     |
 | **a**dvanced    | [Advanced options](./advanced-menu)                                             | Opens another menu with advanced options of CZERTAINLY appliance.                        |
 | **e**xit        | Exit CZERTAINLY manager                                                         | Closes TUI and disconnects from CZERTAINLY appliance.                                    |
@@ -67,6 +69,8 @@ Values you provided in this dialog are stored on the file system in: `/etc/czert
 
 You can change default parameters for Postgres database here. The password is field you definitely should change.
 
+By default CZERTAINLY uses Debian repository where is always only one version of PostgreSQL available, we recomend leaving repostiory settings on value `debian`. In special cases setting it to `official` allows you to choose more than single version. For more details see [official PostgreSQL wiki](https://wiki.postgresql.org/wiki/Apt).
+
 Values you provided in this dialog are stored on the file system in: `/etc/czertainly-ansible/vars/database.yml`.
 
 ## Configure Docker repository access credentials
@@ -75,6 +79,10 @@ Licensed parts of CZERTAINLY are hosted on private Docker repository named `harb
 
 Values you provided in this dialog are stored on the file system in: `/etc/czertainly-ansible/vars/docker.yml`.
 
+## Configure email server parameters
+
+You have to provide parameters of email server. Depending on your company policy hostname of a mail server and a port number might be sufficient. Dialog also offers you chance to configure username, password and TLS usage for authentication to email server if needed.
+
 ## Configure CZERTAINLY
 
 In this dialog window you can select which version and which components of CZERTAINLY you want to install.

docs/10-certificate-key/03-installation-guide/04-deployment/06-deployment-appliance/04-TUI/06-advanced-menu.md

@@ -6,6 +6,7 @@ Advanced menu is used for advanced operations with CZERTAINLY Appliance. You can
 |-----------------|------------------------------------------------------|----------------------------------------------------------------------------------------------|
 | **u**pdate      | Update Operating System                              | This option updates CZERTAINLY Appliance by `apt update && apt upgrade` command.             |
 | **r**emoveC     | [Remove CZERTAINLY](#remove-czertainly)              | This option removes CZERTAINLY Appliance by deleting namespace `czertainly` from Kubernetes. |
+| **i**nstallC    | [Install only CZERTAINLY](#install-only-czertainly)  | This option (re)install only CZERTAINLY, this can quite speedup proces of reinstalation.     |
 | **r**emove      | [Remove RKE2 & CZERTAINLY](#remove-rke2--czertainly) | This option removes RKE2 (Kubernetes) and CZERTAINLY Appliance.                              |
 | **s**hell       | [Enter system shell](#enter-system-shell)            | You can enter system shell as `czertainly` user.                                             |
 | **r**eboot      | Reboot system                                        | This option reboots CZERTAINLY Appliance by `shutdown -r now` command.                       |
@@ -18,6 +19,10 @@ Removing CZERTAINLY from appliance mainly means deleting `czertainly` namespace
 
 This task preserves anything that was configured, including CZERTAINLY data which is stored in Postgres database.
 
+## Install only CZERTAINLY
+
+This tasks only re/install CZERTAINLY software. It is complementary to previous task and reduce reinstallation time comparing to full installation when status of RKE2 is verified. But you have to have operational RKE2 to sucesffuly finish this task.
+
 ## Remove RKE2 & CZERTAINLY
 
 Removing RKE2 (Kubernetes) and CZERTAINLY might be useful when you change hostname or IP address of virtual appliance. This is preparation step for even deeper CZERTAINLY re-installation.

docs/10-certificate-key/03-installation-guide/04-deployment/06-deployment-appliance/05-operations.md

@@ -89,3 +89,81 @@ Default values are stored in file `/root/install/czertainly-values.yaml`. This f
 If you need to provide your own custom Helm chart values that are not available through the [TUI](./TUI/intro), you need to access the shell of the appliance, create file `/home/czertainly/czertainly-values.custom.yaml`, and put it there.
 
 The custom values overwrite the default values during the installation/upgrade process.
+
+### Upgrading
+
+:::warning
+Before any upgrade process make sure you have recent snapshot first!
+:::
+
+#### OS Upgrades
+
+CZERTAINLY Virtual Appliance is based on Debian GNU/Linux. To upgrade it [enter system shell](./TUI/advanced-menu#enter-system-shell), and execute command `sudo apt update && sudo apt upgrade`. This command also upgrades `czertainly-appliance-tools` package, this package provides [TUI](./TUI/intro), it is necessary to close the open shell connection and login back to start using the new version of the TUI.
+
+The new major version of the Debian system is released every 2 years and has [LTS support](https://wiki.debian.org/LTS) lasting typically 5 years in total. The System is designed to support upgrades between major versions by `apt dist-upgrade`, however, we recommend to rather use a new version of CZERTAINLY Virtual Appliance.
+
+#### CZERTAINLY upgrade
+
+It is possible to upgrade CZERTAINLY just by raising the version number in [CZERTAINLY configuration](./TUI/main-menu#configure-czertainly) and executing [CZERTAINLY Instalation](./TUI/main-menu#install-czertainly). It should work for upgrades from version 2.8.0 upwards, but you have to raise the minor version number by 1.
+
+We recommend removing all CZERTAINLY components and installing them back, database with all configurations and all your certificates is untouched during this task. This process involves downtime. Follow the tasks:
+
+Perform [OS upgrade](#os-upgrades). Log out and re-login to open a new session of the TUI.
+
+From the Advanced menu select [Remove RKE2 & CZERTAINLY](./TUI/advanced-menu#remove-rke2--czertainly) this task will remove the Kubernetes cluster together with CZERTAINLY. The database is installed on the OS so it will remain untouched together with CZERTAINLY settings stored in `/etc/czertainly-ansible/vars/`. It is quite quick.
+
+[Configure parameters of email server](./TUI/main-menu#configure-email-server-parameters), this is a new feature of 2.9.0. If you are sure that you do not need notification services, you can disable it in [CZERTAINLY configuration](./TUI/main-menu#configure-czertainly). If you leave the default settings with `hostname` = `mail.example.com` the installation will hang and later timeout.
+
+From version 2.9.0 is it possible to install KeyCloak to allow logging by using username/password. Installing KeyCloak takes some more time, if you are not planning to use it and continue to use certificates, disable KeyCloak inside [CZERTAINLY configuration](./TUI/main-menu#configure-czertainly).
+
+Execute [Install CZETAINLY](TUI/main-menu#install-czertainly) from the main menu. This task will execute Ansible to install the Kubernetes cluster and later to install CZERTAINLY.
+
+### Backup
+
+We suggest to setup periodical snapshoting/backup task of complete appliance on your virtual server platform.
+
+Minimum backup consist:
+* `/home/czertainly`
+* `/etc/czertainly-ansible/vars/`
+* database dump:
+ ```
+ (sudo -u postgres -- pg_dump czertainlydb) > czertainlydb-`date +"%Y-%m-%d-%H:%M:%S"`.dump.sql
+ ```
+
+### Restore
+
+This method is intended mainly for migrating CZERTAINLY from one Appliance to another Appliance, for example when changing a major version of Debian.
+
+First, do a Backup on the old CZERTAINLY Appliance as described above.
+
+Start a brand new instance of Appliance, [upgrade OS](#os-upgrades).
+
+Extract backups of `/home/czertainly` and `/etc/czertainly-ansible/vars/`.
+
+Execute [Install CZETAINLY](TUI/main-menu#install-czertainly) from the main menu. This will install a completely new CZERTAINLY based on your settings.
+
+Stop Kubernetes:
+```
+sudo systemctl stop rke2-server.service
+sudo systemctl stop kubepods.slice
+```
+
+Delete new empty Postgres database:
+```
+echo "DROP DATABASE czertainlydb;" | sudo -u postgres psql
+```
+
+Restore the CZERTAINLY database and populate it with data from your backup:
+```
+export ANSIBLE_CONFIG=/etc/czertainly-ansible/ansible.cfg
+sudo /usr/bin/ansible-playbook /etc/czertainly-ansible/playbooks/czertainly.yml -t postgress
+cat /home/czertainly/czertainlydb-<YYYY-DD-MM-HH:MM:SS>.dump.sql | sudo -u postgres psql czertainlydb
+```
+
+Start Kubernetes:
+```
+sudo systemctl start kubepods.slice
+sudo systemctl start rke2-server.service
+```
+
+Give it several minutes to start and examine the status of CZERTAINLY by command `czertainly-status`.