diff --git a/docs/README.rst b/docs/README.rst index daba743d..61c428e2 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -25,82 +25,7 @@ We report new releases information :ref:`here `. Technical Requirements/Installation ----------------------------------- -**Pre-requirements for Mac OS** - -To install requirements on a Mac, run the following: - -:: - - brew install postgresql etcd haproxy libyaml python - -.. _psycopg2_install_options: - -**Psycopg** - -Starting from `psycopg2-2.8 `__ the binary version of psycopg2 will no longer be installed by default. Installing it from the source code requires C compiler and postgres+python dev packages. -Since in the python world it is not possible to specify dependency as ``psycopg2 OR psycopg2-binary`` you will have to decide how to install it. - -There are a few options available: - -1. Use the package manager from your distro - -:: - - sudo apt-get install python3-psycopg2 # install psycopg2 module on Debian/Ubuntu - sudo yum install python3-psycopg2 # install psycopg2 on RedHat/Fedora/CentOS - -2. Install psycopg2 from the binary package - -:: - - pip install psycopg2-binary - -3. Install psycopg2 from source - -:: - - pip install psycopg2>=2.5.4 - -4. Use psycopg 3.0 instead of psycopg2 - -:: - - pip install psycopg[binary]>=3.0.0 - -**General installation for pip** - -Patroni can be installed with pip: - -:: - - pip install patroni[dependencies] - -where dependencies can be either empty, or consist of one or more of the following: - -etcd or etcd3 - `python-etcd` module in order to use Etcd as Distributed Configuration Store (DCS) -consul - `python-consul` module in order to use Consul as DCS -zookeeper - `kazoo` module in order to use Zookeeper as DCS -exhibitor - `kazoo` module in order to use Exhibitor as DCS (same dependencies as for Zookeeper) -kubernetes - `kubernetes` module in order to use Kubernetes as DCS in Patroni -raft - `pysyncobj` module in order to use python Raft implementation as DCS -aws - `boto3` in order to use AWS callbacks - -For example, the command in order to install Patroni together with dependencies for Etcd as a DCS and AWS callbacks is: - -:: - - pip install patroni[etcd,aws] - -Note that external tools to call in the replica creation or custom bootstrap scripts (i.e. WAL-E) should be installed -independently of Patroni. - +Go :ref:`here ` for guidance on installing and upgrading Patroni on various platforms. .. _running_configuring: diff --git a/docs/index.rst b/docs/index.rst index c7428a95..440f2278 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,6 +22,7 @@ Currently supported PostgreSQL versions: 9.3 to 15. :caption: Contents: README + installation patroni_configuration rest_api replica_bootstrap diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..6c7a6029 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,201 @@ +.. _installation: + +Installation +============ + +Pre-requirements for Mac OS +--------------------------- + +To install requirements on a Mac, run the following: + +.. code-block:: shell + + brew install postgresql etcd haproxy libyaml python + +.. _psycopg2_install_options: + +Psycopg +------- + +Starting from `psycopg2-2.8`_ the binary version of psycopg2 will no longer be installed by default. Installing it from +the source code requires C compiler and postgres+python dev packages. Since in the python world it is not possible to +specify dependency as ``psycopg2 OR psycopg2-binary`` you will have to decide how to install it. + +There are a few options available: + +1. Use the package manager from your distro + +.. code-block:: shell + + sudo apt-get install python3-psycopg2 # install psycopg2 module on Debian/Ubuntu + sudo yum install python3-psycopg2 # install psycopg2 on RedHat/Fedora/CentOS + +2. Install psycopg2 from the binary package + +.. code-block:: shell + + pip install psycopg2-binary + +3. Install psycopg2 from source + +.. code-block:: shell + + pip install psycopg2>=2.5.4 + +4. Use psycopg 3.0 instead of psycopg2 + +.. code-block:: shell + + pip install psycopg[binary]>=3.0.0 + +General installation for pip +---------------------------- + +Patroni can be installed with pip: + +.. code-block:: shell + + pip install patroni[dependencies] + +where ``dependencies`` can be either empty, or consist of one or more of the following: + +etcd or etcd3 + `python-etcd` module in order to use Etcd as Distributed Configuration Store (DCS) +consul + `python-consul` module in order to use Consul as DCS +zookeeper + `kazoo` module in order to use Zookeeper as DCS +exhibitor + `kazoo` module in order to use Exhibitor as DCS (same dependencies as for Zookeeper) +kubernetes + `kubernetes` module in order to use Kubernetes as DCS in Patroni +raft + `pysyncobj` module in order to use python Raft implementation as DCS +aws + `boto3` in order to use AWS callbacks + +For example, the command in order to install Patroni together with dependencies for Etcd as a DCS and AWS callbacks is: + +.. code-block:: shell + + pip install patroni[etcd,aws] + +Note that external tools to call in the replica creation or custom bootstrap scripts (i.e. WAL-E) should be installed +independently of Patroni. + +.. _package_installation: + +Package installation on Linux +----------------------------- + +Patroni packages may be available for your operating system, produced by the Postgres community for: + +* RHEL, RockyLinux, AlmaLinux; +* Debian and Ubuntu; +* SUSE Enterprise Linux. + +You can also find packages for direct dependencies of Patroni, like python modules that might not be available in +the official operating system repositories. + +For more information see the `PGDG repository`_ documentation. + +If you are on a RedHat Enterprise Linux derivative operating system you may also require packages from EPEL, see +`EPEL repository`_ documentation. + +Once you have installed the PGDG repository for your OS you can install patroni. + +.. note:: + + Patroni packages are not maintained by the Patroni developers, but rather by the Postgres community. If you + require support please first try connecting on `Postgres slack`_. + +Installing on Debian derivatives +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With PGDG repo installed, see :ref:`above `, install Patroni via apt run: + +.. code-block:: shell + + apt-get install patroni + +Installing on RedHat derivatives +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With PGDG repo installed, see :ref:`above `, install patroni with an etcd DCS via dnf on RHEL 9 +(and derivatives) run: + +.. code-block:: shell + + dnf install patroni patroni-etcd + +You can install etcd from PGDG if your RedHat derivative distribution does not provide packages. On the nodes that will +host the DCS run: + +.. code-block:: shell + + dnf install 'dnf-command(config-manager)' + dnf config-manager --enable pgdg-rhel9-extras + dnf install etcd + +You can replace the version of RHEL with `8` in the repo to make `pgdg-rhel8-extras` if needed. The repo name is still +`pgdg-rhelN-extras` on RockyLinux, AlmaLinux, Oracle Linux, etc... + +Installing on SUSE Enterprise Linux +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You might need to enable the SUSE PackageHub repositories for some dependencies. see `SUSE PackageHub`_ documentation. + +For SLES 15 with PGDG repo installed, see :ref:`above `, you can install patroni using: + +.. code-block:: shell + + zypper install patroni patroni-etcd + +With the SUSE PackageHub repo enabled you can also install etcd: + +.. code-block:: shell + + SUSEConnect -p PackageHub/15.5/x86_64 + zypper install etcd + +Upgrading +--------- + +Upgrading patroni is a very simple process, just update the software installation and restart the Patroni daemon on +each node in the cluster. + +However, restarting the Patroni daemon will result in a Postgres database restart. In some situations this may cause +a failover of the primary node in your cluster, therefore it is recommended to put the cluster into maintenance mode +until the Patroni daemon restart has been completed. + +To put the cluster in maintenance mode, run the following command on one of the patroni nodes: + +.. code-block:: shell + + patronictl pause --wait + +Then on each node in the cluster, perform the package upgrade required for your OS: + +.. code-block:: shell + + apt-get update && apt-get install patroni patroni-etcd + +Restart the patroni daemon process on each node: + +.. code-block:: shell + + systemctl restart patroni + +Then finally resume monitoring of Postgres with patroni to take it out of maintenance mode: + +.. code-block:: shell + + patronictl resume --wait + +The cluster will now be full operational with the new version of Patroni. + +.. _psycopg2-2.8: http://initd.org/psycopg/articles/2019/04/04/psycopg-28-released/ +.. _PGDG repository: https://www.postgresql.org/download/linux/ +.. _EPEL repository: https://docs.fedoraproject.org/en-US/epel/ +.. _SUSE PackageHub: https://packagehub.suse.com/how-to-use/ +.. _Postgres slack: http://pgtreats.info/slack-invite