repo/native/usage: added intro overview, pg_hbm, links to PG docs

docs/repository/native-postgresql/usage.adoc

@@ -4,9 +4,24 @@
 :page-nav-title: Usage
 :page-since: "4.4"
 
+== Overview
+
+To use midPoint with Native PostgreSQL repository you need to:
+
+. Get the midPoint distribution and install it as described xref:/midpoint/install/distribution/[here];
+you can stop after unpacking the archive and setting up `MIDPOINT_HOME` environment variable.
+. Install and set up the PostgreSQL database - this is the part covered by the bulk of this document.
+. Prepare `config.xml` to configure midPoint for the Native repository.
+Read xref:/midpoint/reference/repository/configuration/[Repository Configuration] for more information,
+including a complete example of `config.xml` for Native repository.
+. Finally, you can run midPoint; this is described in the rest of the xref:/midpoint/install/distribution/[installation document] mentioned in the first step.
+
 == Database setup
 
-=== Installation
+PostgreSQL versions 13 and newer are supported.
+We always recommend using the latest stable version, which as of writing this document is 14.x.
+
+=== Installation and configuration
 
 This guide does not cover the installation process as there are many possible combinations.
 To install PG 13 on Ubuntu 20.04 one can use https://gist.github.com/luizomf/1a7994cf4263e10dce416a75b9180f01[these steps] for an inspiration.
@@ -16,7 +31,7 @@ which is typical for production setup.
 
 The short checklist:
 
-* Install PostgreSQL 13 on your OS or server or VM.
+* Install PostgreSQL 14 on your OS or server or VM.
 * Setup `listen_addresses = '*'` in `postgresql.conf`.
 * While in `postgresql.conf` it's also good to add statements statistics extension and query logging
 for better visibility (the latter may not be a good option for production and small disks).
@@ -25,26 +40,50 @@ See the snippet lower.
 connect to the database remotely.
 * Restart PostgreSQL.
 
-In short, this can all be added to the end `postgresql.conf` (then restart the server):
+==== postgresql.conf
+
+In short, this can all be added to the end `postgresql.conf`:
 
 ----
 listen_addresses = '*'
 
 # this is necessary for pg_stat_statements extension
 shared_preload_libraries = 'pg_stat_statements'
 
-# this is to log all the queries, just be aware of the free disk space
-log_directory = 'pg_log'
-log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'
-log_statement = 'all'
-logging_collector = on
+# To log all queries, uncomment the lines below.
+# Monitor the free disk space afterwards, there is no automatic cleanup!
+#log_directory = 'pg_log'
+#log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'
+#log_statement = 'all'
+#logging_collector = on
 ----
 
 [NOTE]
 Sizing the database server and adjust PostgreSQL configuration parameters is not part
 of this document at this moment - but we plan to add it.
 In the meantime rely on other online resources.
-Be aware that default Postgres server sizing is rather small.
+Be aware that the default Postgres server sizing is rather small.
+You can use a configuration calculator like https://pgtune.leopard.in.ua/[this] to get reasonable
+defaults if you know the DB hardware (use "Mixed type of application" as DB type).
+
+For more information regarding this configuration file read https://www.postgresql.org/docs/current/config-setting.html[this document] from official PostgreSQL documentation.
+
+==== pg_hba.conf
+
+To make things simple, we will allow all connections to the database; password is still required.
+Add the following lines at the end of the `pg_hba.conf` file:
+
+----
+# Allow connections from outside (with password)
+host    all             all             0.0.0.0/0            md5
+----
+
+For more information regarding this configuration file read the https://www.postgresql.org/docs/current/auth-pg-hba-conf.html[official documentation].
+
+==== Restart the server
+
+Any chanes to `postgresql.conf` or `pg_hba.conf` requires PostgreSQL server restart.
+Do so now to apply the configration changes.
 
 === Database preparation
 
@@ -209,10 +248,14 @@ and script for Quartz tables `postgres-new-quartz.sql`.
 
 At this moment the database is prepared and it's time to configure midPoint appropriately.
 This typically preparing proper repository configuration in `config.xml` file.
-Configuration options related to repository as well as example of `config.xml` file can be found
+Configuration options related to repository as well as an example of `config.xml` file can be found
 in xref:/midpoint/reference/repository/configuration/[Repository Configuration] article.
 The article references this page, but if you finished the steps above in this document, you can focus just on the config options.
 
+With the database ready and midPoint configuration file referencing the Native repository,
+you can finally run midPoint, e.g. by running `bin/start.sh`.
+More details on running midPoint are mentioned in the xref:/midpoint/install/distribution/[installation document].
+
 == Versioning and upgrading
 
 Long story short, just run the provided `postgres-new-upgrade.sql` anytime, it should be safe.