diff --git a/docs/debian_remote_quickstart.rst b/docs/debian_remote_quickstart.rst new file mode 100644 index 0000000..9ce09d4 --- /dev/null +++ b/docs/debian_remote_quickstart.rst @@ -0,0 +1,301 @@ +.. _debian_remote_quickstart: + +Remote PoWA Quickstart on Debian +================================ + +.. warning:: + + The current version of PoWA is designed for PostgreSQL 9.4 and newer. If you + want to use PoWA on PostgreSQL < 9.4, please use the `1.x series + `. + +The following describes the installation of a remote setup of PoWA: + * set up the repository + * set up the PoWA Web UI and nginx web server + * set up the collector + * set up a production PostgreSQL instance + * register the instance in PoWA + +.. note:: + + This document only shows how to set up **PoWA in remote mode** targeted to + monitor the activity of **multiple servers** and/or **standby servers**. It + only shows the set-up on a Debian system. + The document assumes that you use the PGDG repository to install PostgreSQL. + Please refer to https://wiki.postgresql.org/wiki/Apt for more informations. + +Architecture +************ + +As the goal of this document is to present how to set up PoWA in remote mode with +multiple PostgreSQL servers monitored, here is the topology of our network: + * powasrv, PoWA repository and Web Server for the UI + * pgsrv1, PostgreSQL database server #1 + +Install the PoWA repository +*************************** + +This step is to be done on server named powasrv. + +The PoWA repository is a PostgreSQL database that stores: +* the configuration of the remote PostgreSQL instances +* the metrics of the remote PostgreSQL instances + +First, install the required packages: + +.. code-block:: bash + + apt install postgresql-14 postgresql-client-14 postgresql-contrib-14 + apt install postgresql-14-powa postgresql-14-pg-qualstats postgresql-14-pg-stat-kcache postgresql-14-hypopg + +Second, set up an new instance, called powa, running PostgreSQL 14, listening on port 50000: + +.. code-block:: bash + + pg_createcluster 14 powa -p 50000 + +Next, add all required modules to `shared_preload_libraries` in the `postgresql.conf` of the +newly created instance: + +.. code-block:: ini + + shared_preload_libraries='pg_stat_statements,powa,pg_stat_kcache,pg_qualstats' + +Restart the instance, as root or using `sudo` : + +.. code-block:: bash + + systemctl restart postgresql@14-powa.service + +Log in to your PostgreSQL as a superuser and create a `powa` database: + +.. code-block:: sql + + CREATE DATABASE powa ; + +Create the required extensions in this new database: + +.. code-block:: sql + + \c powa + CREATE EXTENSION pg_stat_statements; + CREATE EXTENSION btree_gist; + CREATE EXTENSION powa; + CREATE EXTENSION pg_qualstats; + CREATE EXTENSION pg_stat_kcache; + +.. note:: + + If you also installed the pg_wait_sampling extension, don't forget to + modify the shared_preload_libraries accordingly and create the extension too. + + +One last step is to create a role that has superuser privileges and is able to +login to the cluster (use your own credentials): + +.. code-block:: sql + + CREATE ROLE powa SUPERUSER LOGIN PASSWORD 'astrongpassword' ; + +The Web UI requires you to log in with a PostgreSQL role that has superuser +privileges as only a superuser can access to the query text in PostgreSQL. PoWA +follows the same principle. + +The PoWA repository is now up and running on the PostgreSQL-side. You still need to +set up the web interface, set up the collector and set up the remote instances +in order to access your history. + +Install and set up the UI (powa-web) +*************************************** + +This step is to be done on server named powasrv. + +First, install the PoWA web UI: + +.. code-block:: bash + + apt install powa-web + +Let's edit `/etc/powa-web.conf` to point to the repository database: + +.. code-block:: python + servers={ + 'main': { + 'host': '/var/run/postgresql', + 'port': '50000', + 'database': 'powa', + 'query': {'client_encoding': 'utf8'} + } + } + cookie_secret="ed2xoow8shet3eiyai4Odo2OTama2y" + url_prefix="/powa" + port=9999 + address='127.0.0.1' + +The powa-web Web daemon will listen on localhost, on port 9999. The UI will be accessible +under `/powa`. + +Now, install the Nginx Web Server: + +.. code-block:: bash + + apt install nginx-full + +Edit the default nginx server configuration, file `/etc/nginx/sites-enabled/default`. +Let's add a new location `/powa` in the `server` configuration. + +.. code-block:: ini + + server { + listen 80 default_server; + listen [::]:80 default_server; + (...) + location /powa { + include proxy_params; + proxy_pass http://localhost:9999; + } + (...) + +Check the new configuration: + +.. code-block:: bash + + nginx -t + +It should give the following output: + +.. code-block:: + + nginx: the configuration file /etc/nginx/nginx.conf syntax is ok + nginx: configuration file /etc/nginx/nginx.conf test is successful + +Reload nginx: + +.. code-block:: bash + + systemctl reload nginx.service + +Now, the UI throught can be accessed throught the following URL: http://powasrv/powa/ + +To log in, remind the previous creation of user `powa` with password `astrongpassword`. + + + +Install and set up the collector (powa-collector) +**************************************************** + +This step is to be done on server named powasrv. + +.. code-block:: bash + + apt install powa-collector + +Configure the collector to connect to our repository: + +.. code-block:: python + + { + "repository": { + "dsn": "postgresql://powa:astrongpassword@powasrv:50000/powa" + }, + "debug": false + } + +Now enable and restart the service: + +.. code-block:: bash + + systemctl enable powa-collector + systemctl restart powa-collector + +Please visit the configuration page of PoWA to check that the collector is connected: http://powasrv/powa/config/ + + +Install and set up a PostgreSQL instance +**************************************** + +This step is to be done on server pgsrv1 + +First, install the required packages: + +.. code-block:: bash + + apt install postgresql-14 postgresql-client-14 postgresql-contrib-14 + apt install postgresql-14-powa postgresql-14-pg-qualstats postgresql-14-pg-stat-kcache postgresql-14-hypopg + +Second, set up an new instance, called powa, running PostgreSQL 14, listening on port 30001: + +.. code-block:: bash + + pg_createcluster 14 inst1 -p 30001 + +Next, add all required modules to `shared_preload_libraries` in the `postgresql.conf` of the +newly created instance: + +.. code-block:: ini + + shared_preload_libraries='pg_stat_statements,powa,pg_stat_kcache,pg_qualstats' + +Modify file `/etc/postgresql/14/inst1/pg_hba.conf` to permit access to the postgres database to +you powa. Add the following line at the end of the file: + +.. code-block:: ini + + host postgres powa /32 md5 + +Restart the instance, as root or using `sudo` : + +.. code-block:: bash + + systemctl restart postgresql@14-inst1.service + +Log in to your PostgreSQL as a superuser and create a `powa` database: + +.. code-block:: sql + +Create the required extensions in this new database: + +.. code-block:: sql + + \c postgres + CREATE EXTENSION pg_stat_statements; + CREATE EXTENSION btree_gist; + CREATE EXTENSION powa; + CREATE EXTENSION pg_qualstats; + CREATE EXTENSION pg_stat_kcache; + +One last step is to create a role that has superuser privileges and is able to +login to the cluster (use your own credentials): + +.. code-block:: sql + + CREATE ROLE powa SUPERUSER LOGIN PASSWORD 'astrongpassword' ; + +As a final step, get back on `powasrv`, register the instance: + +.. code-block:: bash + + psql -d powa -c "SELECT powa_register_server(hostname => 'pgsrv1', + port => 30001, + alias => 'inst1', + username => 'powa', + password => 'astrongpassword', + dbname => 'postgres', + retention => '7 days', + extensions => '{pg_stat_kcache,pg_qualstats}');" + +And finally, reload the collector: + +.. code-block:: bash + + systemctl reload powa-collector + +.. note:: + + If you also installed the pg_wait_sampling extension, don't forget to + modify the shared_preload_libraries accordingly and create the extension. + Don't forget to add the pg_wait_sampling extension in the extension list of + the register function call. + +Repeat this steps for any other PostgreSQL instance you want to monitor with PoWA. + diff --git a/docs/index.rst b/docs/index.rst index 7088e2c..6d2da37 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -50,7 +50,9 @@ Main components * **Stat extensions** are the actual source of data. * **PoWA** is the whole project. -You should first take a look at the :ref:`quickstart` guide. +You should first take a look at the :ref:`quickstart` guide. If you're more interested +in setting up PoWA in remote mode, take a look at the :ref:`debian_remote_quickstart` +guide. .. toctree::