DISTPG-897 Added install from tarballs documentation (#600)

* Added ETCD to tarball doc * Updated download link * Fixed package description and copy instruction
percona · Jun 24, 2024 · b64fca9 · b64fca9
1 parent 536501e
commit b64fca9
Show file tree

Hide file tree

Showing 4 changed files with 263 additions and 10 deletions.
diff --git a/docs/enable-extensions.md b/docs/enable-extensions.md
@@ -1,18 +1,19 @@
-# 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 extension.
 
-**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. 
 
 While setting up a high availability PostgreSQL cluster with Patroni, you will need the following components:
 
 - Patroni installed on every ``postresql`` node. 
 
-- Distributed Configuration Store (DCS). Patroni supports such DCSs as etcd, zookeeper, Kubernetes though [etcd](https://etcd.io/) is the most popular one. It is available within Percona Distribution for PostgreSQL for all supported operating systems.
-
-- [HAProxy :octicons-link-external-16:](http://www.haproxy.org/).
+- Distributed Configuration Store (DCS). Patroni supports such DCSs as ETCD, zookeeper, Kubernetes though [ETCD](https://etcd.io/) is the most popular one. ETCD is included in Percona distribution for PostgreSQL.
+
+- [HAProxy](http://www.haproxy.org/).
+
 
 See the configuration guidelines for [Debian and Ubuntu](solutions/ha-setup-apt.md) and [RHEL and CentOS](solutions/ha-setup-yum.md). 
 
@@ -25,7 +26,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 +44,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/12/sql-altersystem.html) command. [Connect to psql](connect.md) and use the following command:
 
@@ -53,9 +78,42 @@ ALTER SYSTEM SET shared_preload_libraries = 'set-user';
 
 Start / restart the server to apply the configuration.
 
-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.
+Install the extension into your database:
+
+```sql
+psql <database>
+CREATE EXTENSION set_user;
+```
+
+You can fine-tune user behavior with the [custom parameters](https://github.com/pgaudit/set_user#configuration-options) supplied with the extension.
+
+## 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**
+## wal2json
 
 After the installation, enable the following option in `postgresql.conf` configuration file before starting the service:
 

diff --git a/docs/tarball.md b/docs/tarball.md
@@ -0,0 +1,171 @@
+# 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-{{pgversion}}/{{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
+        ```
+
+11. To use the `createuser` binary to create a database user, set the `LD_LIBRARY_PATH` environment variable to the server's library path.
+
+    ```{.bash data-prompt="$"}
+    export LD_LIBRARY_PATH=/opt/pgdistro/percona-postgresql{{pgversion}}/lib:$LD_LIBRARY_PATH
+    ```
+
+12. 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.
diff --git a/docs/uninstalling.md b/docs/uninstalling.md
@@ -55,3 +55,26 @@ To uninstall Percona Distribution for PostgreSQL, remove all the installed packa
          ```{.bash data-prompt="$"}
          $ rm -rf /var/lib/pgsql/12/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/
+    ```
diff --git a/mkdocs-base.yml b/mkdocs-base.yml
@@ -163,6 +163,7 @@ nav:
       - 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