Merge pull request #5333 from EnterpriseDB/docs/pgd/new/DOCS-122-requ…

…est-for-docs-document-initial-clus

PGD 4 Manual Install DOCS-122

product_docs/docs/pgd/4/deployments/index.mdx

@@ -1,16 +1,18 @@
 ---
 title: "Deployment options"
 indexCards: simple
-
+navigation:
+- tpaexec
+- manually
 ---
 
 You can deploy and install EDB Postgres Distributed products using the following methods:
 
-- TPAexec is an orchestration tool that uses Ansible to build Postgres clusters as specified by TPA (Trusted Postgres Architecture), a set of reference architectures that document how to set up and operate Postgres in various scenarios. TPA represents the best practices followed by EDB, and its recommendations are as applicable to quick testbed setups as to production environments.
+- TPAexec is an orchestration tool that uses Ansible to build Postgres clusters as specified by TPA (Trusted Postgres Architecture), a set of reference architectures that document how to set up and operate Postgres in various scenarios. TPA represents the best practices followed by EDB, and its recommendations are as applicable to quick testbed setups as to production environments. To deploy PGD using TPA, see the [TPA documentation](/admin-tpa/installing/). 
 
-- BigAnimal is a fully managed database-as-a-service with built-in Oracle compatibility, running in your cloud account and operated by the Postgres experts. BigAnimal makes it easy to set up, manage, and scale your databases. The addition of distributed high availability support through EDB Postres Distributed allows single-region or multi-region clusters with one or two data groups. See the [Distributed high availability](/biganimal/latest/overview/02_high_availability/distributed_highavailability/) topic in the [BigAnimal documentation](/biganimal/latest) for more information.
+- Manual installation is also available where TPA is not an option. Details of how to deploy PGD manually are in the [manual installation](/pgd/4/deployments/manually/) section of the documentation.
 
-Coming soon:
+- BigAnimal is a fully managed database-as-a-service with built-in Oracle compatibility, running in your cloud account and operated by the Postgres experts. BigAnimal makes it easy to set up, manage, and scale your databases. The addition of distributed high availability support through EDB Postres Distributed allows single-region or multi-region clusters with one or two data groups. See the [Distributed high availability](/biganimal/latest/overview/02_high_availability/distributed_highavailability/) topic in the [BigAnimal documentation](/biganimal/latest) for more information.
 
-- EDB Postgres Distributed for Kubernetes will be a Kubernetes operator is designed, developed, and supported by EDB that covers the full lifecycle of a highly available Postgres database clusters with a multi-master architecture, using BDR replication. It is based on the open source CloudNativePG operator, and provides additional value such as compatibility with Oracle using EDB Postgres Advanced Server and additional supported platforms such as IBM Power and OpenShift.
+- EDB Postgres Distributed for Kubernetes is a Kubernetes operator is designed, developed, and supported by EDB that covers the full lifecycle of a highly available Postgres database clusters with a multi-master architecture, using BDR replication. It is based on the open source CloudNativePG operator, and provides additional value such as compatibility with Oracle using EDB Postgres Advanced Server and additional supported platforms such as IBM Power and OpenShift.
 

product_docs/docs/pgd/4/deployments/manually/01-provisioning-hosts.mdx

@@ -0,0 +1,75 @@
+---
+title: Step 1 - Provisioning hosts
+navTitle: Provisioning hosts
+deepToC: true
+---
+
+## Provisioning hosts
+
+The first step in the process of deploying PGD is to provision and configure hosts.
+
+You can deploy to virtual machine instances in the cloud with Linux installed, on-premises virtual machines with Linux installed, or on-premises physical hardware, also with Linux installed. 
+
+Whichever [supported Linux operating system](https://www.enterprisedb.com/resources/platform-compatibility#bdr) and whichever deployment platform you select, the result of provisioning a machine must be a Linux system that you can access using SSH with a user that has superuser, administrator, or sudo privileges.
+
+Each machine provisioned must be able to make connections to any other machine you're provisioning for your cluster. 
+
+On cloud deployments, this can be done over the public network or over a VPC. 
+
+On-premises deployments must be able to connect over the local network.
+
+!!! Note Cloud provisioning guides
+
+If you're new to cloud provisioning, these guides may provide assistance:
+
+  Vendor | Platform | Guide
+  ------ | -------- | ------
+  Amazon | AWS      | [Tutorial: Get started with Amazon EC2 Linux instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html)
+  Microsoft | Azure | [Quickstart: Create a Linux virtual machine in the Azure portal](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/quick-create-portal?tabs=ubuntu)
+  Google | GCP | [Create a Linux VM instance in Compute Engine](https://cloud.google.com/compute/docs/create-linux-vm-instance)
+
+!!!
+
+### Configuring hosts
+
+#### Create an admin user
+
+We recommend that you configure an admin user for each provisioned instance. 
+The admin user must have superuser or sudo (to superuser) privileges.
+We also recommend that the admin user be configured for passwordless SSH access using certificates. 
+
+#### Ensure networking connectivity
+
+With the admin user created, ensure that each machine can communicate with the other machines you're provisioning.
+
+In particular, the PostgreSQL TCP/IP port (5444 for EDB Postgres Advanced
+Server, 5432 for EDB Postgres Extended and community PostgreSQL) must be open
+to all machines in the cluster. If you plan to deploy PGD Proxy, its port must be
+open to any applications that will connect to the cluster. Port 6432 is typically
+used for PGD Proxy.
+
+## Worked example
+
+For the example in this section, three hosts are provisioned with Red Hat Enterprise Linux 9.
+
+* `host-one`
+* `host-two`
+* `host-three`
+
+Each is configured with an admin user named admin.
+
+These hosts have been configured in the cloud. As such, each host has both a public and private IP address.
+
+ Name | Public IP | Private IP 
+------|-----------|----------------------
+ host-one | 172.24.117.204 | 192.168.254.166 
+ host-two | 172.24.113.247 | 192.168.254.247
+ host-three | 172.24.117.23 | 192.168.254.135
+
+For this example, the cluster's `/etc/hosts` file was edited to use those private IP addresses:
+
+```
+192.168.254.166 host-one
+192.168.254.247 host-two
+192.168.254.135 host-three
+```

product_docs/docs/pgd/4/deployments/manually/02-install-postgres.mdx

@@ -0,0 +1,66 @@
+---
+title: Step 2 - Installing Postgres
+navTitle: Installing Postgres
+deepToC: true
+---
+
+## Installing Postgres
+
+You need to install Postgres on all the hosts.
+
+An EDB account is required to use the [EDB Repos 2.0](https://www.enterprisedb.com/repos) page where you can get installation instructions.
+Select your platform and Postgres edition. 
+You're presented with two steps of instructions. The first covers how to configure the required package repository and the second covers how to install the packages from that repository.
+
+Run both steps.
+
+## Worked example
+
+In this example, EDB Postgres Advanced Server 14 is installed on Red Hat Enterprise Linux 9 (RHEL 9).
+
+!!! Note
+PGD 4 doesn't support Postgres versions 15, 16, or later.
+!!!
+
+### EDB account
+
+You need an EDB account to install both Postgres and PGD.
+
+Use your EDB account to sign in to the [EDB Repos 2.0](https://www.enterprisedb.com/repos) page where you can select your platform. Then scroll down the list to select the Postgres version you want to install:
+
+* EDB Postgres Advanced Server (up to and including version 14)
+* EDB Postgres Extended (up to and including version 14)
+* PostgreSQL (up to and including version 14)
+
+
+When you select the version of the Postgres server you want, two steps are displayed.
+
+
+### 1: Configuring repositories
+
+For step 1, you can choose to use the automated script or step through the manual install instructions that are displayed. Your EDB repository token will be automatically inserted by the EDB Repos 2.0 site into these scripts. 
+In these examples, the token is shown as `XXXXXXXXXXXXXXXX`.
+
+On each provisioned host, you can run the automatic repository installation script, which looks like this: 
+
+```shell
+curl -1sLf 'https://downloads.enterprisedb.com/XXXXXXXXXXXXXXXX/enterprise/setup.rpm.sh' | sudo -E bash
+```
+
+Or you can use the manual installation steps, which looks like this:
+
+```shell
+dnf install yum-utils 
+rpm --import 'https://downloads.enterprisedb.com/XXXXXXXXXXXXXXXX/enterprise/gpg.E71EB0829F1EF813.key'
+curl -1sLf 'https://downloads.enterprisedb.com/XXXXXXXXXXXXXXXX/enterprise/config.rpm.txt?distro=el&codename=9' > /tmp/enterprise.repo
+dnf config-manager --add-repo '/tmp/enterprise.repo'
+dnf -q makecache -y --disablerepo='*' --enablerepo='enterprisedb-enterprise'
+```
+
+### 2: Install Postgres
+
+For step 2, just run the command to install the packages:
+
+```
+sudo dnf -y install edb-as14-server
+```

product_docs/docs/pgd/4/deployments/manually/03-configuring-repositories.mdx

@@ -0,0 +1,156 @@
+---
+title: Step 3 - Configuring PGD repositories
+navTitle: Configuring PGD repositories
+deepToC: true
+---
+
+## Configuring PGD repositories
+
+To install and run PGD requires that you configure repositories so that the system can download and install the appropriate packages.
+
+Perform the following operations on each host. For the purposes of this exercise, each host will be a standard data node, but the procedure would be the same for other [node types](../../node_management/node_types), such as witness or subscriber-only nodes.
+
+* Use your EDB account.
+  * Obtain your EDB repository token from the [EDB Repos 2.0](https://www.enterprisedb.com/repos-downloads) page.
+
+* Set environment variables. 
+  * Set the `EDB_SUBSCRIPTION_TOKEN` environment variable to the repository token:
+
+    ```
+    export EDB_SUBSCRIPTION_TOKEN=<your-repo-token>
+    ```
+
+* Configure the repository.
+  * Run the automated installer to install the repositories:
+
+    !!! Note Red Hat
+    ```
+    curl -1sLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/setup.rpm.sh" | sudo -E bash
+    ```
+    !!!
+
+    !!! Note Ubuntu/Debian
+    ```
+    curl -1sLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/setup.deb.sh" | sudo -E bash
+    ```
+    !!!
+
+## Worked example
+
+### Use your EDB account
+
+You need an EDB account to install Postgres Distributed. 
+
+Use your EDB account to sign in to the [EDB Repos 2.0](https://www.enterprisedb.com/repos-downloads) page, where you can obtain your repo token. 
+
+On your first visit to this page, select **Request Access** to generate your repo token. 
+
+![EDB Repos 2.0](images/edbrepos2.0.png)
+
+Copy the token to your clipboard using **Copy Token**, and store it safely. 
+
+
+### Set environment variables
+
+Set the `EDB_SUBSCRIPTION_TOKEN` environment variable to the value of your EDB repo token, obtained in the [EDB account](#use-your-edb-account) step.
+
+```
+export EDB_SUBSCRIPTION_TOKEN=<your-repo-token>
+```
+
+You can add this to your `.bashrc` script or similar shell profile to ensure it's always set. 
+
+!!! Note 
+Your preferred platform may support storing this variable as a secret, which can appear as an environment variable. If this is the case, don't add the setting to `.bashrc`. Instead add it to your platform's secret manager.
+!!!
+
+### Configure the repository
+
+All the software you need is available from the EDB Postgres Distributed package repository.
+You have the option to simply download and run a script to configure the EDB Postgres Distributed repository. 
+You can also download, inspect, and then run that same script.
+The following instructions also include the essential steps that the scripts take for any user wanting to manually run, or automate, the installation process.
+
+
+#### RHEL/Other RHEL-based
+
+You can autoinstall with automated OS detection:
+
+```
+curl -1sLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/setup.rpm.sh" | sudo -E bash
+```
+
+If you want to inspect the script that's generated for you, run:
+
+```
+curl -1sLfO "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/setup.rpm.sh"
+```
+
+Then, inspect the resulting `setup.rpm.sh` file. When you're ready to proceed, run:
+
+```
+sudo -E bash setup.rpm.sh
+```
+
+If you want to perform all steps manually or use your own preferred deployment mechanism, you can use the following example as a guide.
+
+You will need to pass details of your Linux distribution and version. You may need to change the codename to match the version of RHEL you're using. This example sets it for RHEL-compatible Linux version 9:
+
+```
+export DISTRO="el"
+export CODENAME="9"
+```
+
+Now install the `yum-utils` package:
+
+```
+sudo dnf install -y yum-utils 
+```
+
+The next step imports a GPG key for the repositories:
+
+```
+sudo rpm --import "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/gpg.44D45428437EAD1B.key"
+```
+
+Now, you can import the repository details, add them to the local configuration, and enable the repository.
+
+```
+curl -1sLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/config.rpm.txt?distro=$DISTRO&codename=$CODENAME" > /tmp/enterprise.repo
+sudo dnf config-manager --add-repo '/tmp/enterprise.repo'
+sudo dnf -q makecache -y --disablerepo='*' --enablerepo='enterprisedb-postgres_distributed'
+```
+
+
+<!---
+
+#### Ubuntu/Debian
+
+You can autoinstall with automated OS detection
+
+```
+curl -1sLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed/_4setup.deb.sh" | sudo -E bash
+```
+
+If you wish to inspect the script that is generated for you:
+
+```
+curl -1sLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/setup.deb.sh" 
+# Inspect setup.deb.sh
+sudo -E bash setup.deb.sh
+```
+
+or if you wish to run all steps manually, the following approach takes on many situations.
+Set the DISTRO environment variable to "ubuntu" or "debian" and the CODENAME environment variable to "jammy" or "focal" (for Ubuntu) or "11"/"12" (for Debian)
+
+```
+export DISTRO="ubuntu"
+export CODENAME="jammy"
+sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https 
+keyring_location=/usr/share/keyrings/enterprisedb-postgres_distributed-archive-keyring.gpg
+curl -1sLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/gpg.44D45428437EAD1B.key" |  gpg --dearmor | sudo tee ${keyring_location} >/dev/null
+curl -1sLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed_4/config.deb.txt?distro=$DISTRO&codename=$CODENAME" | sudo tee /etc/apt/sources.list.d/enterprisedb-postgres_distributed.list >/dev/null
+sudo apt-get update
+```
+
+--->