DISTPG-897 Documented install from tarball steps for PG server (#560)

* DISTPG-897 Documented install from tarball steps for PG server

* Added how to run extensions, extended the Enable extensions page

.python-version

@@ -0,0 +1 @@
+3.11.1

docs/enable-extensions.md

@@ -1,8 +1,8 @@
-# Enable Percona Distribution for PostgreSQL extensions
+# Enable Percona Distribution for PostgreSQL components
 
-Some extensions require additional configuration before using them with Percona Distribution for PostgreSQL. This sections provides configuration instructions per extension.
+Some components require additional configuration before using them with Percona Distribution for PostgreSQL. This sections provides configuration instructions per component.
 
-**Patroni**
+## Patroni
 
 Patroni is the third-party high availability solution for PostgreSQL. The [High Availability in PostgreSQL with Patroni](solutions/high-availability.md) chapter provides details about the solution overview and architecture deployment. 
 
@@ -25,7 +25,7 @@ See the configuration guidelines for [Debian and Ubuntu](solutions/ha-setup-apt.
 
         - [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios :octicons-link-external-16:](https://www.percona.com/blog/2021/06/11/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) 
         
-**pgBadger**
+## pgBadger
 
 Enable the following options in `postgresql.conf` configuration file before starting the service:
 
@@ -43,7 +43,31 @@ log_error_verbosity = default
 
 For details about each option, see [pdBadger documentation :octicons-link-external-16:](https://github.com/darold/pgbadger/#POSTGRESQL-CONFIGURATION).
 
-**pgAudit set-user**
+## pgaudit
+
+Add the `pgaudit` to `shared_preload_libraries` in `postgresql.conf`. The recommended way is to use the [ALTER SYSTEM](https://www.postgresql.org/docs/16/sql-altersystem.html) command. [Connect to psql](#connect-to-the-postgresql-server) and use the following command:
+
+```sql
+ALTER SYSTEM SET shared_preload_libraries = 'pgaudit';
+```
+
+Start / restart the server to apply the configuration.
+
+To configure `pgaudit`, you must have the privileges of a superuser. You can specify the settings in one of these ways:
+
+*  globally (in postgresql.conf or using ALTER SYSTEM ... SET), 
+* at the database level (using ALTER DATABASE ... SET), 
+* at the role level (using ALTER ROLE ... SET). Note that settings are not inherited through normal role inheritance and SET ROLE will not alter a user's pgAudit settings. This is a limitation of the roles system and not inherent to pgAudit. 
+
+Refer to the [pgaudit documentation](https://github.com/pgaudit/pgaudit/blob/master/README.md#settings) for details about available settings.
+
+To enable `pgaudit`, connect to psql and run the CREATE EXTENSION command:
+
+```sql
+CREATE EXTENSION pgaudit;
+```
+
+## pgaudit set-user
 
 Add the `set-user` to `shared_preload_libraries` in `postgresql.conf`. The recommended way is to use the [ALTER SYSTEM :octicons-link-external-16:](https://www.postgresql.org/docs/16/sql-altersystem.html) command. [Connect to psql](connect.md) and use the following command:
 
@@ -53,16 +77,52 @@ ALTER SYSTEM SET shared_preload_libraries = 'set-user';
 
 Start / restart the server to apply the configuration.
 
+Install the extension into your database:
+
+```sql
+psql <database>
+CREATE EXTENSION set_user;
+```
+
 You can fine-tune user behavior with the [custom parameters :octicons-link-external-16:](https://github.com/pgaudit/set_user#configuration-options) supplied with the extension.
 
-**wal2json**
+## pgbouncer
+
+`pgbouncer` requires the `pgbouncer.ini` configuration file to start. The default path is `/etc/pgbouncer/pgbouncer.ini`. When installing `pgbouncer` from a [tarball](tarball.md), the path is `percona-pgbouncer/etc/pgbouncer.ini`.
+
+Find detailed information about configuration file options in the [`pgbouncer documentation`](https://www.pgbouncer.org/config.html).
+
+## pgpool2
+
+`pgpool-II` requires the configuration file to start. When you install pgpool from a package, the configuration file is automatically created for you at the path `/etc/pgpool2/pgpool.conf` on Debian and Ubuntu and `/etc/pgpool-II/pgpool.conf` on RHEL and derivatives.
+
+When you installed pgpool from tarballs, you can use the sample configuration file `<tarballsdir>/percona-pgpool-II/etc/pgpool2/pgpool.conf.sample`:
+
+```{.bash data-prompt="$"}
+$ cp <tarballsdir>/percona-pgpool-II/etc/pgpool2/pgpool.conf.sample <config-gile-path>/pgpool.conf
+```
+
+Specify the path to it when starting pgpool:
+
+```{.bash data-prompt="$"}
+$ pgpool -f <config-gile-path>/pgpool.conf
+```
+
+## pg_stat_monitor
+
+Please refer to [`pg_stat_monitor`](pg-stat-monitor.md#setup) for setup steps.
+
+## wal2json
 
 After the installation, enable the following option in `postgresql.conf` configuration file before starting the service:
 
 ```
 wal_level = logical
 ```
 
+Start / restart the server to apply the changes.
+
 ## Next steps 
 
-[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button}
+[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button}
+

docs/index.md

@@ -49,5 +49,34 @@ Learn about the releases and changes in the Distribution.
 </div>
 </div>
 
+* [Patroni](https://patroni.readthedocs.io/en/latest/) is an HA (High Availability) solution for PostgreSQL.
+
+* [pgaudit](https://www.pgaudit.org/) provides detailed session or object
+audit logging via the standard PostgreSQL logging facility
+
+* [pgaudit set_user](https://github.com/pgaudit/set_user) - The `set_user` part of `pgAudit` extension provides an additional layer of logging and control when unprivileged users must escalate themselves to superuser or object owner roles in order to perform needed maintenance tasks.
+
+* [pgBackRest](https://pgbackrest.org/) is a backup and restore solution for
+PostgreSQL
+
+* [pgBadger](https://github.com/darold/pgbadger) - a fast PostgreSQL Log Analyzer.
+
+* [PgBouncer](https://www.pgbouncer.org/) - a lightweight connection pooler for PostgreSQL
+
+* [pg_gather](https://github.com/jobinau/pg_gather) - an SQL script to assess the health of PostgreSQL cluster by gathering performance and configuration data from PostgreSQL databases.
+
+* [pgpool2](https://www.pgpool.net/mediawiki/index.php/Main_Page) - a middleware between PostgreSQL server and client for high availability, connection pooling and load balancing.
+
+* [pg_repack](https://github.com/reorg/pg_repack) rebuilds
+PostgreSQL database objects
+
+* [pg_stat_monitor](https://github.com/percona/pg_stat_monitor) collects and aggregates statistics for PostgreSQL and provides histogram information.
+
+* [PostGIS](http://postgis.net/) allows storing and manipulating spacial data in PostgreSQL.
+
+* [wal2json](https://github.com/eulerto/wal2json) - a PostgreSQL logical decoding JSON output plugin.
+
+* A collection of [additional PostgreSQL contrib extensions](https://www.postgresql.org/docs/{{pgversion}}/contrib.html)
+
 
 

docs/tarball.md

@@ -0,0 +1,165 @@
+# Install Percona Distribiution for PostgreSQL from binary tarballs
+
+You can find the binary tarballs on the [Percona website](https://www.percona.com/downloads). Select the desired version from a version dropdown and _All_ from the Select Platform dropdown.
+
+There are the following tarballs available: 
+
+* percona-postgresql-{{dockertag}}-ssl1.1-linux-x86_64.tar.gz  - for operating systems that run OpenSSL version 1.x
+* percona-postgresql-{{dockertag}}-ssl3-linux-x86_64.tar.gz - for for operating systems that run OpenSSL version 3.x
+
+To check what OpenSSL version you have, run the following command: 
+
+```{.bash data-prompt="$"}
+$ openssl version
+```
+
+## Tarball contents
+
+The tarballs include the following components:
+
+| Component | Description |
+|-----------|-------------|
+| percona-postgresql{{pgversion}}| The latest version of PostgreSQL server and the following extensions: <br> - `pgaudit` <br> - `pgAudit_set_user` <br> - `pg_repack` <br> - `pg_stat_monitor` <br> - `pg_gather` <br> - `wal2json` <br> -  the set of [contrib extensions](contrib.md)|
+| percona-haproxy | A high-availability solution and load-balancing solution |
+| percona-patroni | A high-availability solution for PostgreSQL |
+| percona-pgbackrest| A backup and restore tool |
+| percona-pgbadger| PostgreSQL log analyzer with fully detailed reports and graphs |
+| percona-pgbouncer| Lightweight connection pooler for PostgreSQL |
+| percona-pgpool-II| A middleware between PostgreSQL server and client for high availability, connection pooling and load balancing |
+| percona-perl | A Perl module required to create the `plperl` extension - a procedural language handler for PostgreSQL that allows writing functions in the Perl programming language|
+| percona-python3 | A Python3 module required to create `plpython` extension - a procedural language handler for PostgreSQL that allows writing functions in the Python programming language. Python is also required by Patroni
+| percona-tcl | Tcl development libraries required to create the `pltcl` extension - a loadable procedural language for the PostgreSQL database system that enables the creation of functions and trigger procedures in the Tcl language |
+| percona-etcd | A key-value distributed store that stores the state of the PostgreSQL cluster|
+
+## Preconditions
+
+=== "Debian and Ubuntu"
+
+    1. Uninstall the upstream PostgreSQL package. 
+    2. Create the user to own the PostgreSQL process. For example, `mypguser`. Run the following command:
+
+        ```{.bash data-prompt="$"}
+        $ sudo useradd -m mypguser
+        ```
+
+        Set the password for the user:
+
+        ```{.bash data-prompt="$"}
+        $ sudo passwd mypguser
+        ```
+
+=== "RHEL and derivatives"
+
+    Create the user to own the PostgreSQL process. For example, `mypguser`, Run the following command: 
+        
+    ```{.bash data-prompt="$"}
+    $ sudo useradd mypguser -m 
+    ```
+
+    Set the password for the user:
+
+    ```{.bash data-prompt="$"}
+    $ sudo passwd mypguser
+    ```
+
+## Procedure
+
+The steps below install the tarballs for OpenSSL 3.x. Use another tarball if your operating system has OpenSSL version 1.x.
+
+1. Create the directory where you will store the binaries. For example, `/opt/pgdistro`
+
+2. Grant access to this directory for the `mypguser` user.
+
+    ```{.bash data-prompt="$"}
+    $ sudo chown mypguser:mypguser /opt/pgdistro/
+    ```
+
+3. Fetch the binary tarball:
+
+    ```{.bash data-prompt="$"}
+    $ wget https://downloads.percona.com/downloads/postgresql-distribution-16/{{dockertag}}/binary/tarball/percona-postgresql-{{dockertag}}-ssl3-linux-x86_64.tar.gz
+    ```
+
+4. Extract the tarball to the directory for binaries that you created on step 1.
+
+    ```{.bash data-prompt="$"}
+    $ sudo tar -xfv percona-postgresql-{{dockertag}}-ssl3-linux-x86_64.tar.gz -C /opt/pgdistro/
+    ```
+
+5. If you extracted the tarball in a directory other than `/opt`, copy `percona-python3`, `percona-tcl` and `percona-perl` to the `/opt` directory. This is required for the correct run of libraries that require those modules. 
+
+    ```{.bash data-prompt="$"}
+    $ sudo cp <path_to>/percona-perl <path_to>/percona-python3 <path_to>/percona-tcl /opt/
+    ```
+
+6. Add the location of the binaries to the PATH variable:
+
+    ```{.bash data-prompt="$"}
+    $ export PATH=:/opt/pgdistro/percona-haproxy/sbin/:/opt/pgdistro/percona-patroni/bin/:/opt/pgdistro/percona-pgbackrest/bin/:/opt/pgdistro/percona-pgbadger/:/opt/pgdistro/percona-pgbouncer/bin/:/opt/pgdistro/percona-pgpool-II/bin/:/opt/pgdistro/percona-postgresql{{pgversion}}/bin/:/opt/pgdistro/percona-etcd/bin/:/opt/percona-perl/bin/:/opt/percona-tcl/bin/:/opt/percona-python3/bin/:$PATH
+    ```
+
+6. Create the data directory for PostgreSQL server. For example, `/usr/local/pgsql/data`.
+7. Grant access to this directory for the `mypguser` user.
+
+    ```{.bash data-prompt="$"}
+    $ sudo chown mypguser:mypguser /usr/local/pgsql/data
+    ```
+
+8. Switch to the user that owns the Postgres process. In our example, `mypguser`:
+
+    ```{.bash data-prompt="$"}
+    $ su - mypguser
+    ```
+
+9. Initiate the PostgreSQL data directory:
+
+    ```{.bash data-prompt="$"}
+    $ /opt/pgdistro/percona-postgresql{{pgversion}}/bin/initdb -D /usr/local/pgsql/data
+    ```
+
+
+    ??? example "Sample output"
+
+        ```{.text .no-copy}
+        Success. You can now start the database server using:
+
+        /opt/pgdistro/percona-postgresql{{pgversion}}/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
+        ```
+
+10. Start the PostgreSQL server:
+
+    ```{.bash data-prompt="$"}
+    $ /opt/pgdistro/percona-postgresql{{pgversion}}/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
+    ```
+
+    ??? example "Sample output"
+
+        ```{.text .no-copy}
+        waiting for server to start.... done
+        server started
+        ```
+
+9. Connect to `psql`
+
+    ```{.bash data-prompt="$"}
+    $ /opt/pgdistro/percona-postgresql{{pgversion}}/bin/psql
+    ```
+
+    ??? example "Sample output"
+
+        ```{.text .no-copy}
+        psql ({{dockertag}})
+        Type "help" for help.
+
+        postgres=#
+        ```
+
+### Start the components
+
+After you unpacked the tarball and added the location of the components' binaries to the $PATH variable, the components are available for use. You can invoke a component by running its command-line tool. For example, to check HAProxy version, type:
+
+```{.bash data-prompt="$"}
+$ haproxy version
+```
+
+Some components require additional setup. Check the [Enabling extensions](enable-extensions.md) page for details.

docs/uninstalling.md

@@ -60,3 +60,26 @@ To uninstall Percona Distribution for PostgreSQL, remove all the installed packa
          ```{.bash data-prompt="$"}
          $ rm -rf /var/lib/pgsql/16/data
          ```
+
+## Uninstall from tarballs
+
+If you [installed Percona Distribution for PostgreSQL from binary tarballs](tarball.md), stop the PostgreSQL server and remove the folder with the binary tarballs.
+
+1. Stop the `postgres` server:
+
+    ```{.bash data-prompt="$"}
+    $ /path/to/tarballs/percona-postgresql{{pgversion}}/bin/pg_ctl -D path/to/datadir -l logfile stop
+    ```
+
+    ??? example "Sample output"
+
+        ```{.text .no-copy}
+        waiting for server to shut down.... done
+        server stopped
+        ```
+
+2. Remove the directory with extracted tarballs
+
+    ```{.bash data-prompt="$"}
+    $ sudo rm -rf /path/to/tarballs/
+    ```

mkdocs-base.yml

@@ -152,11 +152,13 @@ extra:
 
 nav:
   - 'Home': 'index.md'
+
   - Get started: 
       - Quickstart guide: installing.md
       - 1. Install: 
           - Via apt: apt.md
           - Via yum: yum.md
+          - From tarballs: tarball.md
           - Run in Docker: docker.md
           - enable-extensions.md
           - repo-overview.md