Single-Node Installation

Get started with Pigsty—complete single-node install on a fresh Linux host!

Tutorial

PIGSTY

This is the Pigsty single-node install guide Single Node. For multi-node HA production deployment, refer to the Deployment docs.

Pigsty single-node installation consists of three steps: Install, Configure, and Deploy.

Summary

Prepare a node with compatible OS, and run as an admin user with nopass ssh and sudo:

Choose a Pigsty download mirror:

pigsty.io (Global)

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

pigsty.cc (China)

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

This command runs the install script, downloads and extracts Pigsty source to your home directory and installs dependencies. Then complete Configure and Deploy:

Enter the Source Directory

cd ~/pigsty

Generate the Inventory

./configure -g

Skip this step if you already have a prepared pigsty.yml.

Run the Deployment Playbook

./deploy.yml

After installation, access the Web UI via IP/domain + port 80/443 through Nginx, and access the default PostgreSQL service via port 5432.

The complete process takes 3–10 minutes depending on server specs/network. Offline installation speeds this up significantly; for monitoring-free setups, use Slim Install for even faster deployment.

Video Example: Online Single-Node Installation (Debian 13, x86_64)

demo/install-hero.cast

Prepare

Installing Pigsty involves some preparation work. Here’s a checklist.

For single-node installations, many constraints can be relaxed—typically you only need to know your IP address. If you don’t have a static IP, 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

Typically, you only need to focus on your local IP address—as an exception, for single-node deployment, use 127.0.0.1 if no static IP available.

Install

Use the following commands to auto-install Pigsty source to ~/pigsty (recommended). Deployment dependencies (Ansible) are installed automatically.

Choose a Pigsty download mirror:

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

If you prefer not to run a remote script, you can manually download or clone the source. When using git, always checkout a specific version before use.

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

For manual download/clone installations, run the bootstrap script to install Ansible and other dependencies. You can also install them yourself.

./bootstrap           # Install ansible for subsequent deployment

Configure

In Pigsty, deployment blueprints are defined by the inventory, the pigsty.yml configuration file. You can customize through declarative configuration.

Pigsty provides the configure script as an optional configuration wizard, which generates an inventory with good defaults based on your environment and input:

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

The generated config file is at ~/pigsty/pigsty.yml by default. Review and customize as needed before installation.

Many configuration templates are available for reference. You can skip the wizard and directly edit pigsty.yml:

./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 the current main branch (v5.0.0-preview). If you install another version, the first line reports that version.

Current main branch configure output

Example 1 Example configure output from the current main branch

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 = vagrant@127.0.0.1 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 = vagrant@10.10.10.12 ok
[ OK ] mode = meta (el9)
[ OK ] locale  = C.UTF-8
[ OK ] configure pigsty done
proceed with ./deploy.yml

Common configure Arguments

-i | --ip , IPv4: The primary private IP of the current host, used to replace the 10.10.10.10 placeholder in the inventory.
-c | --conf , string: A configuration template name relative to conf/, without the .yml suffix.
-v | --version , integer: PostgreSQL major version 14 through 19; PG19 is Beta, so use the dedicated pg19 template.
-r | --region , enum , defaultdefault: Upstream repository region for faster downloads: default, china, or europe.
-n | --non-interactive , boolean , defaultfalse: Use command-line arguments for the primary IP and skip the interactive wizard.
-x | --proxy , boolean , defaultfalse: Use current environment variables to configure proxy_env.

If your machine has multiple IPs bound, use -i|--ip <ipaddr> to explicitly specify the primary IP, or provide it in the interactive prompt. The script replaces the placeholder 10.10.10.10 with your node’s primary IPv4 address. Choose a static IP; do not use public IPs.

Change default passwords!

We strongly recommend modifying default passwords and credentials in the config file before installation. See Security Recommendations for details.

Deploy

Pigsty’s deploy.yml playbook applies the blueprint from Configure to target nodes.

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

Example 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

When you see pgsql init done, PLAY RECAP and similar output at the end, installation is complete!

Upstream repo changes may cause online installation failures!

Upstream repos used by Pigsty (like Linux/PGDG repos) can sometimes enter a broken state due to improper updates, causing deployment failures (this has happened multiple times)! You can wait for upstream fixes or use pre-made offline packages to solve this.

Avoid re-running the deployment playbook!

Warning: Running deploy.yml again on an existing deployment may restart services and overwrite configurations!

Interface

After single-node installation, you typically have four modules installed 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`

The INFRA module provides a graphical management interface, accessible via Nginx on ports 80/443.

The PGSQL module provides a PostgreSQL database server, listening on 5432, also accessible via Pgbouncer/HAProxy proxies.

Use the current node as a base to deploy and monitor more clusters: add cluster definitions to the inventory and run:

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

Most modules require the NODE module installed first. See available modules for details:

PGSQL, INFRA, NODE, ETCD, MINIO, REDIS, DOCKER……