Single-Node Installation

Install, configure, and deploy Pigsty on one Linux node.

This guide installs Pigsty on one Linux node. Single Node For production deployments with multiple nodes, use the Deployment Guide.

The procedure has three stages: Install, Configure, and Deploy.

Summary

Prepare a node with a supported operating system. Use an administration account with passwordless SSH and sudo access.

Select a download source and run its command:

pigsty.io (Global)

curl -fsSL https://repo.pigsty.io/get | bash

pigsty.cc (China)

curl -fsSL https://repo.pigsty.cc/get | bash

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

Then do these steps:

Enter the Source Directory

Run this command:

cd ~/pigsty

Generate the Inventory

Run this command to generate the configuration file and random passwords:

./configure -g

If you already have a prepared pigsty.yml, skip this step.

Run the Deployment Playbook

Run this command:

./deploy.yml

After deployment, open the Web UI through Nginx on port 80 or 443. Use the node IP address or domain name. Connect to the default PostgreSQL service on port 5432.

The procedure usually takes 3–10 minutes. The duration depends on the server resources and network speed. Offline installation can reduce the duration. If you do not need monitoring, use Slim Installation to install fewer components.

Example: online installation on Debian 13, x86_64

demo/install-hero.cast

Prepare

Review the preparation requirements. For a single-node installation, first identify the node IP address. If the node has no static IP address, you can use 127.0.0.1.

Item	Requirement	Item	Requirement
Node	1-node, at least `1C2G`, no upper limit	Disk	`/data` mount point, `xfs` recommended
OS	`Linux` `x86_64` / `aarch64`, EL/Debian/Ubuntu	Network	Static IPv4; single-node without fixed IP can use `127.0.0.1`
SSH	`nopass` SSH login via public key	SUDO	sudo privilege, preferably with `nopass` option

The 127.0.0.1 exception applies to single-node installations.

Install

Use one of these commands to install Pigsty into ~/pigsty. The script also installs Ansible and other deployment dependencies.

pigsty.io (Global)

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

pigsty.cc (China)

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

You can also 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

If you download or clone the source manually, run bootstrap to install the dependencies:

./bootstrap           # Install ansible for subsequent deployment

You can also install Ansible manually.

Configure

The inventory defines the deployment. Pigsty uses pigsty.yml as the default inventory file. Edit this file to change the deployment configuration.

The configure script is an optional configuration wizard. It generates an inventory from your environment and input. Run it with -g to generate random passwords:

./configure -g                # Use config 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                  # Default template, install PG 18 with essential extensions
./configure -v 16            # Use PG 16 instead of default PG 18
./configure -c rich          # Create local repo, download all extensions, install major ones
./configure -c slim          # Minimal install template, use with ./slim.yml playbook
./configure -c app/supa      # Use app/supa self-hosted Supabase template
./configure -c ivory         # Use IvorySQL kernel instead of native PG
./configure -i 10.11.12.13   # Explicitly specify primary IP address
./configure -r china         # Use China mirrors instead of default repos
./configure -c ha/full -s    # Use 4-node sandbox template, skip IP replacement/detection

The output below is from v4.5.0. If you install a different version, the first line shows that version.

Example 1 Configuration output from the current release

Configuration output

vagrant@meta:~/pigsty$ ./configure

configure pigsty v4.5.0 begin
[ OK ] region  = default
[ OK ] kernel  = Linux
[ OK ] machine = x86_64
[ OK ] package = rpm,dnf
[ OK ] vendor  = rocky (Rocky Linux)
[ OK ] version = 9 (9.6)
[ OK ] sudo = vagrant ok
[ OK ] ssh = [email protected] ok
[WARN] Multiple IP address candidates found:
    (1) 192.168.121.24	inet 192.168.121.24/24 brd 192.168.121.255 scope global dynamic noprefixroute eth0
    (2) 10.10.10.12	    inet 10.10.10.12/24 brd 10.10.10.255 scope global noprefixroute eth1
[ IN ] INPUT primary_ip address (of current meta node, e.g 10.10.10.10):
=> 10.10.10.12    # <------- INPUT YOUR PRIMARY IPV4 ADDRESS HERE!
[ OK ] primary_ip = 10.10.10.12 (from input)
[ OK ] admin = [email protected] ok
[ OK ] mode = meta (el9)
[ OK ] locale  = C.UTF-8
[ OK ] configure pigsty done
proceed with ./deploy.yml

Common configure Arguments

-i | --ip , IPv4: Set the primary private IPv4 address of the current node. The script replaces 10.10.10.10 in the inventory with this address.
-c | --conf , string: Select a configuration template relative to conf/. Omit the .yml suffix.
-v | --version , integer: Select a PostgreSQL major version from 14 through 19. PostgreSQL 19 is Beta. Use the dedicated pg19 template for that version.
-r | --region , enum , defaultdefault: Select the upstream repository region: default, china, or europe. Use the region that gives faster downloads.
-n | --non-interactive , boolean , defaultfalse: Supply the primary IP address through command-line arguments. Skip the interactive wizard.
-x | --proxy , boolean , defaultfalse: Use the current environment variables to configure proxy_env.

If the node has multiple IP addresses, specify the primary address with -i|--ip <ipaddr>. You can also enter the address at the interactive prompt. Use a static private IPv4 address. Do not use a public IP address.

Replace default credentials before deployment

Default credentials are public. Replace them in pigsty.yml before deployment. See Security Recommendations for the credentials that configure -g does not replace.

Deploy

The deploy.yml playbook applies the inventory to the target nodes. Run it from the Pigsty source directory:

./deploy.yml     # Deploy the defined modules in the core path at once

Deployment output

......

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

At the end, look for pgsql init done and PLAY RECAP. Make sure that the target nodes report failed=0 and unreachable=0.

Upstream repository changes can stop installation

Changes to Linux or PGDG repositories can break package dependencies. If installation fails for this reason, wait for the upstream correction. You can also use offline packages.

Repeated deployment can change running services

If Pigsty is already deployed, another run of deploy.yml can restart services. It can also overwrite configuration files. Examine the required changes before you run the playbook again.

Interface

A default single-node installation puts four modules on the current node: PGSQL, INFRA, NODE, and ETCD.

ID	NODE	PGSQL	INFRA	ETCD
1	`10.10.10.10`	`pg-meta-1`	`infra-1`	`etcd-1`

INFRA supplies the Web UI through Nginx on ports 80 and 443. PGSQL supplies the PostgreSQL service on port 5432. You can also connect through PgBouncer or HAProxy.

Use the current node to deploy and monitor additional clusters. First add their definitions to the inventory. Then run the applicable commands:

bin/node-add   pg-test      # Add the 3 nodes of cluster pg-test 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

Install the NODE module first when the target module requires it. See the module reference for dependencies. Available modules include PGSQL, INFRA, ETCD, MINIO, REDIS, and DOCKER.