Install Pigsty for Production

This guide describes production deployment on multiple nodes. For single-node demonstrations or development, use Getting Started.

Summary

1. Prepare the nodes according to your architecture plan.
2. Install a supported Linux operating system.
3. Configure SSH access.
4. Use an administration account with passwordless ssh and sudo access.
5. Run the installation command:

curl -fsSL https://repo.pigsty.io/get | bash;         # International
curl -fsSL https://repo.pigsty.cc/get | bash;         # Backup Mirror

The installation script downloads and extracts Pigsty into your home directory. It also installs the dependencies. Then complete configuration and deployment.

Before you run deploy.yml, examine and edit pigsty.yml. This file is the configuration inventory.

cd ~/pigsty      # Enter Pigsty directory
./configure -g   # Generate config file (optional, skip if you know how to configure)
./deploy.yml     # Execute deployment playbook based on generated config

After deployment, open the Web UI through the IP address or domain on ports 80/443. Connect to PostgreSQL on port 5432.

Installation usually takes 3-10 minutes, depending on server resources and network speed. Offline installation can reduce this time. If you do not need monitoring, Slim Installation installs fewer components and takes less time.

Example: 20-node production simulation on Ubuntu 24.04, x86_64

Prepare

Use this checklist to complete the deployment preparations:

Install

Use one of these commands to install the Pigsty source package into ~/pigsty. This method is recommended and also installs Ansible and other deployment dependencies.

curl -fsSL https://repo.pigsty.io/get | bash            # Install current default version
curl -fsSL https://repo.pigsty.io/get | bash -s v4.5.0  # Explicitly install the current public stable release

curl -fsSL https://repo.pigsty.cc/get | bash            # Install current default version
curl -fsSL https://repo.pigsty.cc/get | bash -s v4.5.0  # Explicitly install the current public stable release

You can instead download a release or clone the source repository. If you use git, select a released version before deployment:

git clone https://github.com/pgsty/pigsty; cd pigsty;
git checkout v4.5.0;  # Always checkout a released tag when using git

After a manual download or clone, run bootstrap to install Ansible and the other dependencies. You can also install them yourself.

./bootstrap           # Install ansible for subsequent deployment

Configure

The inventory defines the deployment configuration. Pigsty uses pigsty.yml as the default configuration file. Edit it to define the required deployment.

The configure script is an optional configuration wizard. It generates an inventory with defaults for your environment:

./configure -g                # Use wizard to generate config with random passwords

The default output file is ~/pigsty/pigsty.yml. Examine this file and make the necessary changes before deployment.

Use the configuration templates as examples. You can also edit pigsty.yml directly without the wizard:

./configure -c ha/full -g       # Use 4-node sandbox template
./configure -c ha/trio -g       # Use 3-node minimal HA template
./configure -c ha/dual -g -v 18 # Use 2-node semi-HA template with PG 18
./configure -c ha/simu -s       # Use 20-node production simulation, skip IP check, no random passwords

vagrant@meta:~/pigsty$ ./configure
configure pigsty v4.5.0 begin
[ OK ] region = china
[ OK ] kernel  = Linux
[ OK ] machine = x86_64
[ OK ] package = deb,apt
[ OK ] vendor  = ubuntu (Ubuntu)
[ OK ] version = 22 (22.04)
[ OK ] sudo = vagrant ok
[ OK ] ssh = [email protected] ok
[WARN] Multiple IP address candidates found:
    (1) 192.168.121.38	    inet 192.168.121.38/24 metric 100 brd 192.168.121.255 scope global dynamic eth0
    (2) 10.10.10.10	    inet 10.10.10.10/24 brd 10.10.10.255 scope global eth1
[ OK ] primary_ip = 10.10.10.10 (from demo)
[ OK ] admin = [email protected] ok
[ OK ] mode = meta (ubuntu22.04)
[ OK ] locale  = C.UTF-8
[ OK ] ansible = ready
[ OK ] pigsty configured
[WARN] don't forget to check it and change passwords!
proceed with ./deploy.yml

The wizard replaces only the current node IP address. Use -s to skip this replacement. For multiple nodes, replace the other IP addresses manually. Change default passwords, add nodes, and adjust other configuration values for your environment.

Common configure parameters:

If the node has multiple IP addresses, select its primary address with -i|--ip <ipaddr> or enter it interactively. The script replaces 10.10.10.10 with the current node’s primary IPv4 address. Use a static private address. Do not use a public IP address.

Review the generated ~/pigsty/pigsty.yml before deployment.

Deploy

The deploy.yml playbook applies the configuration to all target nodes:

./deploy.yml     # Deploy core modules on all target nodes at once

......

TASK [pgsql : pgsql init done] *************************************************
ok: [10.10.10.11] => {
    "msg": "postgres://10.10.10.11/postgres | meta  | dbuser_meta dbuser_view "
}
......

TASK [pg_monitor : load grafana datasource meta] *******************************
changed: [10.10.10.11]

PLAY RECAP *********************************************************************
10.10.10.11                : ok=302  changed=232  unreachable=0    failed=0    skipped=65   rescued=0    ignored=1
localhost                  : ok=6    changed=3    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

Interface

The 4-node template creates this deployment structure:

The INFRA module supplies the Web UI through Nginx on ports 80/443. The PGSQL module supplies a PostgreSQL server on port 5432. You can also connect through PgBouncer or HAProxy.

For production HA clusters, use service access to route traffic automatically.

More

After installation, open the Web UI and connect to PostgreSQL on port 5432. To deploy and monitor additional clusters, add their definitions to the inventory. Then run the applicable commands:

bin/node-add   pg-test      # Add pg-test cluster's 3 nodes to Pigsty management
bin/pgsql-add  pg-test      # Initialize a 3-node pg-test HA PG cluster
bin/redis-add  redis-ms     # Initialize Redis cluster: redis-ms

Most modules require the NODE module first. See the module reference. Available modules include PGSQL, INFRA, NODE, ETCD, MINIO, REDIS, and DOCKER.