Get Started

• 1: Single-Node Installation
• 2: Docker Deployment
• 3: Web Interface
• 4: Getting Started with PostgreSQL
• 5: Customize Pigsty with Configuration
• 6: Run Playbooks with Ansible
• 7: Offline Installation
• 8: Slim Installation
• 9: Security Recommendations

curl -fsSL https://repo.pigsty.io/get | bash  # Install Pigsty and dependencies
cd ~/pigsty; ./configure -g                   # Generate config (with 1-node template, -g generates random passwords)
./deploy.yml                                  # Execute deployment playbook

1 - Single-Node Installation

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:

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

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:

cd ~/pigsty

./configure -g

./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 — /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.

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.

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

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.

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

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.

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

......

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

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

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.

More

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.

2 - Docker Deployment

Pigsty runs on native Linux. It can also run in Linux containers with systemd. If you use macOS or Windows, use Docker to try a local single-node installation.

Quick Start

Enter the docker/ source directory. Run the launch command:

cd ~/pigsty/docker
make launch          # Start container + generate config + deploy

After deployment, use these addresses and commands to connect:

The make launch command runs ./configure -g to generate random passwords. Use this command to find the generated passwords:

cd ~/pigsty/docker
make pass | grep -E 'grafana_admin_password|pg_admin_password'

Prepare

Make sure that the host meets these requirements:

Make sure that host ports 2222, 8080, 8443, and 5432 are available. If a port is in use, change its mapping in .env before launch.

Image

Pigsty supplies the pgsty/pigsty image on Docker Hub.

The image supports amd64 (x86_64) and arm64. The ARM architecture includes Apple Silicon and AWS Graviton. Image tags follow Pigsty versions. The latest and v4.5.0 tags point to the current release. Select a version tag for repeatable deployment.

The image uses Debian 13 (Trixie). It includes systemd, SSH, the pig command-line tool, Ansible, and initialized Pigsty source. The Docker configuration template prepares it for ./deploy.yml.

Launch

Use the commands in the docker/ directory. The make launch command starts the container, generates its configuration, and runs deployment:

cd ~/pigsty/docker
make launch          # One-liner: up + config + deploy

To examine each stage separately, run the commands in this order:

cd ~/pigsty/docker
make up              # Start container
make exec            # Enter container
./configure -c docker -g --ip 127.0.0.1  # Generate config (optional, pre-configured)
./deploy.yml         # Execute deployment

To build the image locally, use these commands:

cd ~/pigsty/docker
make build           # Build image locally
make launch          # Start container + generate config + deploy

Config

Set the image version and port mappings in .env:

PIGSTY_VERSION=v4.5.0         # Current main source default; verify the remote tag before pulling
PIGSTY_SSH_PORT=2222          # SSH port
PIGSTY_HTTP_PORT=8080         # Nginx HTTP port
PIGSTY_HTTPS_PORT=8443        # Nginx HTTPS port
PIGSTY_PG_PORT=5432           # PostgreSQL port

The port variables map host ports to container ports:

If a default host port is in use, supply a different value through an environment variable:

PIGSTY_HTTP_PORT=8888 docker compose up -d

Commands

The Docker Makefile supplies commands to manage containers and images. Run these commands from the Docker source directory.

Docker Compose

Use Docker Compose for the standard deployment procedure:

make up           # Start container
make down         # Stop and remove container
make start        # Start stopped container
make stop         # Stop container
make restart      # Restart container
make pull         # Pull latest image
make config       # Run ./configure in container
make deploy       # Run ./deploy.yml in container
make launch       # One-liner: up + config + deploy

Container Access

Use these commands to enter the container or open a service client:

make exec         # Enter container bash
make ssh          # SSH into container
make log          # View container logs
make status       # View systemd status
make ps           # View process list
make conf         # View config file
make pass         # View passwords in config

Image Build

Use these commands to build images:

make build        # Build image locally
make buildnc      # Build without cache
make push         # Build and push multi-arch image

Image Management

Use these commands to manage images:

make save         # Export image to pigsty-<version>-<arch>.tgz
make load         # Import image from tgz file
make rmi          # Remove current version's pigsty image

Cleanup

Use these commands to remove the selected resources:

make clean        # Stop and remove container
make purge        # Stop and remove the container, then directly delete ./data in the current directory

Manual Run

To start the container with docker run, use this command:

mkdir -p ./data
docker run -d --privileged --name pigsty \
  -p 2222:22 -p 8080:80 -p 5432:5432 \
  -v ./data:/data \
  pgsty/pigsty:<version>

docker exec -it pigsty ./configure -c docker -g --ip 127.0.0.1
docker exec -it pigsty ./deploy.yml

You can also use the Makefile command:

make run          # Start with docker run
make exec         # Enter container
make clean        # Stop and remove container
make purge        # Remove container and directly delete ./data in the current directory

How It Works

The image uses Debian 13 (Trixie) with systemd as the initialization system. Manage services inside the container with systemctl, as on native Linux.

The container has these properties:

• Systemd manages the services.
• SSH permits root access with the password pigsty.
• The --privileged option supplies the access required by systemd.
• The /data volume keeps data outside the container.
• The image includes pig, Ansible, and initialized Pigsty source.

The image build runs these initialization steps:

# Install pig CLI
RUN echo "deb [trusted=yes] https://repo.pigsty.io/apt/infra/ generic main" \
    > /etc/apt/sources.list.d/pigsty.list \
    && apt-get update && apt-get install -y pig

# Initialize Pigsty source and install Ansible
RUN pig sty init -v ${PIGSTY_VERSION} \
    && pig sty boot \
    && pig sty conf -c docker --ip 127.0.0.1

The ./configure -c docker command selects the Docker configuration template. This template uses 127.0.0.1 as the default IP address and applies settings for the container environment.

FAQ

Container won’t start

Make sure that Docker is installed and the host meets the resource requirements. On Docker Desktop, allocate at least 2 GB of memory. Examine ports 2222, 8080, 8443, and 5432 for conflicts.

Can’t access services

Make sure that ./deploy.yml completed successfully. The Web Portal and PostgreSQL require this deployment stage. Run make status to see the service status.

Port conflicts

Change the port in .env or supply an environment variable:

PIGSTY_HTTP_PORT=8888 PIGSTY_PG_PORT=5433 docker compose up -d

Data persistence

The host directory ./data stores persistent container data. To remove this data and start again, use these commands:

make purge        # Remove container and directly delete ./data in the current directory (no countdown)

The purge step deletes the existing data. Back up any required data first.

macOS performance

Docker Desktop on macOS uses a virtual machine. This adds overhead compared with native Linux. Use Docker for development and testing. For production, use native Linux installation.

More

• Docker Hub supplies the image.
• Source Directory contains the Docker configuration and Makefile.
• Native Linux Installation describes single-node deployment.
• Offline Installation describes installation without Internet access.
• Deployment Guide describes production deployment.

3 - Web Interface

The default single-node installation includes the INFRA module. This module installs an Nginx web server on the node. Nginx supplies the Web UI and proxies requests to the monitoring services and other component interfaces.

Access

Enter the deployment node IP address in your browser. By default, Nginx uses port 80 for HTTP and port 443 for HTTPS. Replace 10.10.10.10 in these examples with your node IP address.

Monitoring

To open the Grafana dashboards, add /ui to the server address:

If the service is accessible from the Internet or an office network, use a domain name. Enable HTTPS to encrypt the connection.

Endpoints

Nginx uses these paths to proxy requests to the components. Open each path through the server HTTP or HTTPS address. The native port is the port of the component behind Nginx.

Domain Access

Point your domain name to the Pigsty server IP address. Set the domain in the home server configuration. This configuration is part of infra_portal:

all:
  vars:
    infra_portal:
      home : { domain: i.pigsty } # Replace i.pigsty with your domain

To use a Let’s Encrypt certificate, also set certbot:

all:
  vars:
    infra_portal:  # domain specifies the domain name  # certbot parameter specifies certificate name
      home : { domain: demo.pigsty.io ,certbot: mycert }

After deployment, run make cert to request the free Let’s Encrypt certificate.

If you omit certbot, Pigsty uses the local certificate authority (CA) to issue an HTTPS certificate. Add the Pigsty CA to your browser trust store before you use that certificate.

You can also configure Nginx to serve local directories or proxy other upstream services. See Nginx Management for the procedure.

4 - Getting Started with PostgreSQL

PostgreSQL is an open-source relational database. It can store and retrieve different types of data. This guide uses PG as an abbreviation for PostgreSQL.

Use this guide if you know basic Linux commands and want to start with PostgreSQL in Pigsty. The examples use the default single-node installation. For production clusters with multiple nodes, see Service Access.

Basics

The default single-node template creates the pg-meta cluster on the current node. This cluster has one primary instance. PostgreSQL listens on port 5432. The template also creates the meta database.

After installation, close your administration account SSH session. Log in again to load the new environment variables. Enter pp to open psql:

vagrant@pg-meta-1:~$ pp
psql (18.6 (Ubuntu 18.6-1.pgdg24.04+1))
Type "help" for help.

postgres=#

The command uses p as a shortcut for the pig command-line tool. You can also use the postgres operating system account to run psql. This connects to the default postgres administration database.

Connecting to Database

Use a command-line tool or a graphical client to connect. Supply a PostgreSQL connection string in this format:

postgres://username:password@host:port/dbname

Some drivers and clients require separate connection parameters:

For personal administration, you can use dbuser_dba. This account is a database superuser with full privileges.

If you ran configure -g, the script generated a random administration password. Find the password in ~/pigsty/pigsty.yml:

cat ~/pigsty/pigsty.yml | grep pg_admin_password

Default Accounts

The default single-node template defines these database accounts:

These examples connect to the same meta database with different accounts:

postgres://dbuser_dba:[email protected]:5432/meta
postgres://dbuser_meta:[email protected]:5432/meta
postgres://dbuser_view:[email protected]:5432/meta

Replace the example IP address and password with your actual values. The configure -g command replaces the three example passwords with random passwords. See Security Recommendations for its complete scope and limitations.

Using CLI Tools

psql is the PostgreSQL command-line client. On a Pigsty node, use one of these methods to connect to the local database:

# Simplest way: use postgres system user for local connection (no password needed)
sudo -u postgres psql

# Use connection string (recommended, most universal)
psql 'postgres://dbuser_dba:[email protected]:5432/meta'

# Use parameter form
psql -h 10.10.10.10 -p 5432 -U dbuser_dba -d meta

# Use env vars to avoid password appearing in command line
export PGPASSWORD='DBUser.DBA'
psql -h 10.10.10.10 -p 5432 -U dbuser_dba -d meta

Replace the example IP address and password before you run the connection commands. After a successful connection, psql shows a prompt:

psql (18.6)
Type "help" for help.

meta=#

Common psql commands

Enter SQL statements at the prompt. To run a psql meta-command, start the command with \.

SQL example

End each SQL statement with a semicolon (;). This example creates a test table, adds two rows, queries the rows, and removes the table:

-- Check PostgreSQL version
SELECT version();

-- Check current time
SELECT now();

-- Create a test table
CREATE TABLE test (id SERIAL PRIMARY KEY, name TEXT, created_at TIMESTAMPTZ DEFAULT now());

-- Insert data
INSERT INTO test (name) VALUES ('hello'), ('world');

-- Query data
SELECT * FROM test;

-- Drop test table
DROP TABLE test;

Using Graphical Clients

You can also connect with a graphical client.

Grafana

The INFRA module includes Grafana and a PostgreSQL data source named Meta. Open the Web UI. Use the Grafana Explore panel to query PostgreSQL with SQL. This method requires no additional client software.

The default Grafana username is admin. Find its password in grafana_admin_password in the inventory. The default password is pigsty.

DataGrip

DataGrip is a database development tool from JetBrains. IntelliJ IDEA also has a Database Console that can connect to PostgreSQL.

DBeaver

DBeaver is a free, open-source database client. It runs on multiple desktop operating systems and supports PostgreSQL and other databases.

pgAdmin

pgAdmin is a PostgreSQL administration client from PGDG. You can use its browser interface or desktop application. Pigsty supplies a pgAdmin template for deployment with Docker.

Viewing Monitoring Dashboards

Pigsty supplies PostgreSQL monitoring dashboards. They show information from cluster summaries to individual tables.

Open PGSQL Overview first. Select a cluster to see its instances and databases. Use the dashboard links to examine tables, indexes, and functions.

Trying Extensions

PostgreSQL extensions add data types, functions, index methods, and other database features. Pigsty packages 600 extensions in 16 categories. These categories include time-series data, geographic data, vectors, and full-text search.

Start with these extensions:

• postgis processes geographic and location data. The default template installs it.
• pgvector supplies vector similarity search for AI embeddings. The default template installs it.
• timescaledb stores and queries time-series data. Install it when required.

Use these commands to list and enable extensions:

\dx                            -- psql meta command, list installed extensions
TABLE pg_available_extensions; -- Query installed, available extensions
CREATE EXTENSION postgis;      -- Enable postgis extension

Next Steps

Change the configuration to define your databases, users, and extensions.

5 - Customize Pigsty with Configuration

You can generate a configuration file with the configuration wizard. You can also write the file yourself. This guide builds an inventory in stages.

The deploy.yml playbook deploys NODE, INFRA, ETCD, MINIO, and PGSQL when the inventory defines them. Docker, Redis, Kafka, native MySQL, JUICE, and VIBE require their own playbooks. The procedures below show the configuration and playbooks for each stage.

Minimal Configuration

The smallest valid configuration defines admin_ip. This is the IP address of the administration node where you installed Pigsty:

all: { vars: { admin_ip: 10.10.10.10 } }

# Set region: china to use mirrors
all: { vars: { admin_ip: 10.10.10.10, region: china } }

This inventory defines no deployment targets. With this configuration, ./deploy.yml generates a self-signed certificate authority (CA) in files/pki/ca. The CA issues certificates for the deployment.

Set region to select a software repository region. The available values are default, china, and europe.

Add Nodes

The NODE module manages the nodes in the inventory. Add a node IP address to include that node in NODE module deployment:

all:  # Remember to replace 10.10.10.10 with your actual IP
  children: { nodes: { hosts: { 10.10.10.10: {} } } }
  vars:
    admin_ip: 10.10.10.10                   # Current node IP
    region: default                         # Default repos
    node_repo_modules: node,pgsql,infra     # Add node, pgsql, infra repos

all:  # Remember to replace 10.10.10.10 with your actual IP
  children: { nodes: { hosts: { 10.10.10.10: {} } } }
  vars:
    admin_ip: 10.10.10.10                 # Current node IP
    region: china                         # Use mirrors
    node_repo_modules: node,pgsql,infra   # Add node, pgsql, infra repos

These examples add two global parameters:

• node_repo_modules selects the software repositories to add.
• region selects the repository region.

The NODE module uses these repositories to install the required packages. Other NODE parameters control node names, DNS, NTP, kernel parameters, tuning, monitoring, and log collection. You can use the default values for the initial deployment.

Run node.yml to apply the NODE configuration. The deploy.yml playbook also includes this stage.

Add Infrastructure

The infrastructure supplies monitoring, alerting, dashboards, NTP, and DNS. To deploy the INFRA module, define the infra group:

all:  # Simply changed group name from nodes -> infra and added infra_seq
  children: { infra: { hosts: { 10.10.10.10: { infra_seq: 1 } } } }
  vars:
    admin_ip: 10.10.10.10
    region: default
    node_repo_modules: node,pgsql,infra

all:  # Simply changed group name from nodes -> infra and added infra_seq
  children: { infra: { hosts: { 10.10.10.10: { infra_seq: 1 } } } }
  vars:
    admin_ip: 10.10.10.10
    region: china
    node_repo_modules: node,pgsql,infra

Set infra_seq to identify each INFRA node. This identity parameter distinguishes nodes in deployments with multiple INFRA nodes.

Run infra.yml to install INFRA and NODE on 10.10.10.10:

./infra.yml   # Install INFRA module on infra group (includes NODE module)

demo/infra.cast — /demo/infra.cast

The inventory IP address also defines the NODE deployment target. NODE tasks are idempotent: they apply the changes necessary to reach the specified configuration.

After this stage, the node has monitoring services and node monitoring. It does not yet have a PostgreSQL database service.

If you only need Grafana and Victoria monitoring, you can stop here. The infra template supports this use. Pigsty also supports PostgreSQL without the infrastructure through Slim Installation.

Deploy Database Cluster

To add PostgreSQL, define the PGSQL module and its ETCD dependency:

all:
  children:
    infra:   { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:    { hosts: { 10.10.10.10: { etcd_seq:  1 } } } # Add etcd cluster
    pg-meta: { hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }, vars: { pg_cluster: pg-meta } } # Add pg cluster
  vars: { admin_ip: 10.10.10.10, region: default, node_repo_modules: 'node,pgsql,infra' }

all:
  children:
    infra:   { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:    { hosts: { 10.10.10.10: { etcd_seq:  1 } } } # Add etcd cluster
    pg-meta: { hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }, vars: { pg_cluster: pg-meta } } # Add pg cluster
  vars: { admin_ip: 10.10.10.10, region: china, node_repo_modules: 'node,pgsql,infra' }

The etcd group defines a single-node etcd cluster. The pg-meta group defines a single-node PostgreSQL cluster.

Install ETCD first. PGSQL uses ETCD for high-availability consensus. Run the module playbooks in this order:

./etcd.yml  -l etcd      # Install ETCD module on etcd group
./pgsql.yml -l pg-meta   # Install PGSQL module on pg-meta group

You can also apply the core modules together with ./deploy.yml. Before another deployment run, review the effects on existing services. After these playbooks complete successfully, PostgreSQL is available.

The procedures use four playbooks to deploy four modules on one node:

• node.yml deploys NODE.
• infra.yml deploys INFRA.
• etcd.yml deploys ETCD.
• pgsql.yml deploys PGSQL.

Define Databases and Users

Define PostgreSQL databases and users in the inventory:

all:
  children:
    # Other groups and variables hidden for brevity
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_users:       # Define database users
          - { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user  }
        pg_databases:   # Define business databases
          - { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [vector] }

pg_users defines the dbuser_meta account with the example password DBUser.Meta. pg_databases defines the meta database with the vector extension. It also loads the optional Pigsty CMDB schema. Replace the example password before deployment.

Database and user parameters control their properties. If you define these parameters before deployment, pgsql.yml creates the databases and users.

For an existing cluster, use these commands to create or change users and databases:

bin/pgsql-user pg-meta dbuser_meta      # Ensure user dbuser_meta exists in pg-meta
bin/pgsql-db   pg-meta meta             # Ensure database meta exists in pg-meta

Configure PG Version and Extensions

Pigsty supports multiple PostgreSQL major versions and 600 extensions. The example below replaces PostgreSQL 18 with PostgreSQL 16. This procedure recreates pg-meta; it is not an in-place version change.

Before removal, back up the cluster and confirm the target. Use check mode to examine the removal tasks:

./pgsql-rm.yml -l pg-meta --check # Preflight old pg-meta removal; execute only after backup and target confirmation

The --check command does not perform the removal. Complete the required removal before you recreate the cluster.

Set these parameters in the new configuration:

• pg_extensions installs timescaledb, postgis, and pgvector packages.
• pg_libs loads the timescaledb, pg_stat_statements, and auto_explain libraries.
• pg_databases enables vector, postgis, and timescaledb in the meta database.

all:
  children:
    infra:   { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:    { hosts: { 10.10.10.10: { etcd_seq:  1 } } } # Add etcd cluster
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_version: 16   # Specify PG version as 16
        pg_extensions: [ timescaledb, postgis, pgvector ]      # Install these extensions
        pg_libs: 'timescaledb,pg_stat_statements,auto_explain'  # Preload these extension libraries
        pg_databases: [ { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [vector, postgis, timescaledb ] } ]
        pg_users: [ { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles: [dbrole_admin] ,comment: admin user } ]

  vars:
    admin_ip: 10.10.10.10
    region: default
    node_repo_modules: node,pgsql,infra

Then run the PostgreSQL deployment playbook:

./pgsql.yml -l pg-meta   # Install PG16 and extensions, recreate pg-meta cluster

Add More Nodes

Add the new node definitions to the inventory. Run bin/node-add to configure monitoring and repositories and install the node packages. Select the complete group or individual IP addresses:

# Add entire cluster at once, or add nodes individually
bin/node-add pg-test

bin/node-add 10.10.10.11
bin/node-add 10.10.10.12
bin/node-add 10.10.10.13

demo/node.cast — /demo/node.cast

Deploy HA PostgreSQL Cluster

Define the pg-test cluster on the three new nodes. Set one node as the primary and two nodes as replicas:

all:
  children:
    infra:   { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:    { hosts: { 10.10.10.10: { etcd_seq: 1 } }, vars: { etcd_cluster: etcd } }
    pg-meta: { hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }, vars: { pg_cluster: pg-meta } }
    pg-test:
      hosts:
        10.10.10.11: { pg_seq: 1, pg_role: primary }
        10.10.10.12: { pg_seq: 2, pg_role: replica  }
        10.10.10.13: { pg_seq: 3, pg_role: replica  }
      vars: { pg_cluster: pg-test }

Deploy the cluster with the PGSQL playbook or its bin/pgsql-add wrapper. See the high-availability requirements for the ETCD topology.

demo/pgsql.cast — /demo/pgsql.cast

Deploy Redis Cluster

Pigsty supports Redis as an optional cache for PostgreSQL applications. After you define a Redis cluster in the inventory, run the applicable command:

bin/redis-add redis-ms
bin/redis-add redis-meta
bin/redis-add redis-test

For Redis high availability, use cluster mode or sentinel mode. See Redis Configuration.

Deploy Silo Object Storage

The MINIO module deploys Silo object storage. Silo implements the S3 interface and can store PostgreSQL backups. The module, inventory group, and playbooks keep the minio name for compatibility.

Run the module playbook:

./minio.yml -l minio

A production Silo deployment typically requires at least four nodes with four disks per node (4N/16D).

Deploy Docker Module

To run PostgreSQL tools and applications in containers, install the DOCKER module:

./docker.yml -l infra

Use an application template to deploy the required software. For example, run this command to deploy pgAdmin:

./app.yml    -l infra -e app=pgadmin

You can also deploy Supabase with Pigsty. Supabase uses an external HA PostgreSQL cluster for its database and containers for its stateless components.

6 - Run Playbooks with Ansible

Pigsty uses Ansible to deploy and manage clusters. Ansible applies declarative configuration through playbooks. Pigsty module playbooks use idempotent tasks to reach the specified configuration.

For a single-node installation, use deploy.yml. Other built-in playbooks perform specific module operations. Ansible knowledge helps you manage Pigsty, but the single-node procedure does not require it.

Deploy Playbook

The deploy.yml playbook applies the core deployment configuration. It includes the CA, software repository, NODE, INFRA, ETCD, PGSQL, and MINIO when the inventory enables them. Optional modules such as Redis, Kafka, and native MySQL require their own playbooks. Defining these optional modules in the inventory does not add them to deploy.yml.

The table shows the module deployment targets:

You can apply the core configuration in one run with deploy.yml. For deployment in stages, follow the Customization Guide.

Install Ansible

The Pigsty installation script installs Ansible and its dependencies. The offline bootstrap procedure can also install them.

To install Ansible manually, use the command for your operating system. The minimum supported Ansible version is 2.9.

sudo apt install -y ansible python3-jmespath

sudo dnf install -y ansible python3.12-jmespath python3-cryptography  # EL 8
sudo dnf install -y ansible python3-jmespath                           # EL 9
sudo dnf install -y ansible                                            # EL 10

brew install ansible
pip3 install jmespath

On macOS, install Ansible with Homebrew. You can use the Mac as an administration node for remote cloud servers. This method is suitable for personal single-node deployments. For production, use a Linux administration node.

Execute Playbook

Ansible playbooks are executable YAML files with task definitions. Make sure that ansible-playbook is available through your PATH environment variable. The command ./node.yml runs ansible-playbook node.yml.

Use these four arguments to control execution:

./node.yml                         # Run node playbook on all hosts
./pgsql.yml -l pg-test             # Run pgsql playbook on pg-test cluster
./infra.yml -t repo_build          # Run infra.yml subtask repo_build
./pgsql-rm.yml -l pg-test -e pg_rm_pkg=false --check # Preflight removal while keeping packages
./infra.yml -i conf/mynginx.yml    # Use another location's config file

Limit Hosts

Use -l|--limit <selector> to select the target hosts or groups. The selector can contain an IP address, group name, or pattern.

./pgsql.yml                              # Run on all hosts (dangerous!)
./pgsql.yml -l pg-test                   # Run on pg-test cluster
./pgsql.yml -l 10.10.10.10               # Run on single host 10.10.10.10
./pgsql.yml -l pg-*                      # Run on hosts/groups matching glob `pg-*`
./pgsql.yml -l '10.10.10.11,&pg-test'    # Run on 10.10.10.11 in pg-test group
./pgsql-rm.yml -l 'pg-test,!10.10.10.11' --check # Preflight removal; verify target and backups before execution

See the Ansible host and group patterns for the selection rules.

Limit Tasks

Use -t|--tags <tags> to select tasks by tag. This limits execution to the selected tasks instead of the complete playbook:

./infra.yml -t repo          # Create repo
./node.yml  -t node_pkg      # Install node packages
./pgsql.yml -t pg_install    # Install PG packages and extensions
./etcd.yml  -t etcd_config   # Render ETCD configuration again
./minio.yml -t minio_alias   # Write the mcli client alias

To select multiple tags, separate them with commas:

./node.yml  -t node_repo,node_pkg   # Add repos, then install packages
./pgsql.yml -t pg_hba,pg_reload     # Configure, then reload pg hba rules

Extra Vars

Use -e|--extra-vars KEY=VALUE to override configuration parameters for one run. These variables have the highest variable precedence. You can supply -e more than once:

# Create admin using another admin user
./node.yml -e ansible_user=admin -k -K -t node_admin

# Initialize a specific Redis instance: 10.10.10.11:6379
./redis.yml -l 10.10.10.10 -e redis_port=6379 -t redis

# Remove PostgreSQL but keep packages and data
./pgsql-rm.yml -l pg-test -e pg_rm_pkg=false -e pg_rm_data=false --check

For lists, objects, or multiple variables, supply a JSON string:

# Add repo and install packages
./node.yml -t node_install -e '{"node_repo_modules":"infra","node_packages":["duckdb"]}'

Specify Inventory

The default inventory is pigsty.yml in the Pigsty source directory. Use -i <path> to select a different inventory file:

./pgsql.yml -i conf/rich.yml            # Initialize single node with all extensions per rich config
./pgsql.yml -i conf/ha/full.yml         # Initialize 4-node cluster per full config
./pgsql.yml -i conf/app/supa.yml        # Initialize 1-node Supabase deployment per supa.yml

Convenience Scripts

The bin/ directory contains scripts for common operations. Each script calls an Ansible playbook with the necessary arguments:

bin/node-add   <cls>            # Add nodes to Pigsty management: ./node.yml -l <cls>
bin/node-rm    <cls>            # Remove nodes from Pigsty: ./node-rm.yml -l <cls>
bin/pgsql-add  <cls>            # Initialize PG cluster: ./pgsql.yml -l <cls>
bin/pgsql-rm   <cls>            # Remove PG cluster: ./pgsql-rm.yml -l <cls>
bin/pgsql-user <cls> <username> # Add business user: ./pgsql-user.yml -l <cls> -e username=<user>
bin/pgsql-db   <cls> <dbname>   # Add business database: ./pgsql-db.yml -l <cls> -e dbname=<db>
bin/redis-add  <cls>            # Initialize Redis cluster: ./redis.yml -l <cls>
bin/redis-rm   <cls>            # Remove Redis cluster: ./redis-rm.yml -l <cls>

Use these scripts when their operation matches your task.

Playbook List

The table lists the built-in playbooks. You can add your own playbooks or change their tasks for your deployment requirements.

7 - Offline Installation

Pigsty normally installs packages from upstream Internet repositories. If the environment has no Internet access, use offline packages.

Overview

An offline package contains the RPM or DEB packages and dependencies from a local APT or YUM repository. It records the repository contents after an online installation.

Use offline packages for production deployments when you need consistent package versions. They let new nodes use the same packages as the existing nodes. They also remove the installation dependency on upstream repository availability.

Offline Packages

The v4.5.0 release supplies offline packages for seven recommended operating system versions. Each version has an x86_64 package and an aarch64 package. The fourteen artifacts are available from GitHub:

The GitHub release page also supplies a checksums manifest. Each artifact has a detached PGP signature with the .asc suffix. The published MD5 checksums are:

e042059379bdfae8f774022b89e8d1e3  pigsty-pkg-v4.5.0.el9.aarch64.tgz
997e812a433a6b969b976fad2c023a1f  pigsty-pkg-v4.5.0.el9.x86_64.tgz
1e1045db965282d564680534bd7d72e2  pigsty-pkg-v4.5.0.el10.aarch64.tgz
9a53f1e85cbb2d4f85969a6112ae4b05  pigsty-pkg-v4.5.0.el10.x86_64.tgz
b7501783c90311176f21bdd35390c746  pigsty-pkg-v4.5.0.d12.aarch64.tgz
f3ecaa449a0bf8e0f01907f83831e74a  pigsty-pkg-v4.5.0.d12.x86_64.tgz
863165dba76b044ed8615d6743710005  pigsty-pkg-v4.5.0.d13.aarch64.tgz
d86655361ccad7aa95a345a82bb37d10  pigsty-pkg-v4.5.0.d13.x86_64.tgz
017f2d7931eb644d2d0fa2f71930134e  pigsty-pkg-v4.5.0.u26.aarch64.tgz
61451ee610134423ff08f1a69dfced33  pigsty-pkg-v4.5.0.u26.x86_64.tgz
5d9cfc52a25545b56e73e94ab5b5e175  pigsty-pkg-v4.5.0.u24.aarch64.tgz
dba0eef49899509d1524b3a1c37d0ddc  pigsty-pkg-v4.5.0.u24.x86_64.tgz
5564841c7c099489708cd1fe49ffa1b9  pigsty-pkg-v4.5.0.u22.aarch64.tgz
dc52b6cee50cf6226e23b065e5aa8395  pigsty-pkg-v4.5.0.u22.x86_64.tgz
afb5cd77903613cb945bd519e4059c76  pigsty-v4.5.0.tgz

Using Offline Packages

Do these steps in order:

1. Download the matching offline package and save it as /tmp/pkg.tgz.
2. Download and extract the Pigsty source package into your home directory.
3. Run cd ~/pigsty to enter the source directory.
4. Run ./bootstrap to extract the offline package, configure the local repository, and install Ansible.
5. Run ./configure -g -c rich to select the rich template and generate random passwords.
6. Run ./deploy.yml to install the core modules from the local repository.

You can also use your own configuration with the repository settings below. Other optional modules still require their own playbooks.

demo/install-offline.cast — /demo/install-offline.cast

To use an extracted offline package with your own configuration, set these parameters:

• Set repo_enabled to true to enable the local software repository.
• Set node_repo_modules to local to install all packages from that repository.

Most templates disable repository creation and select node,infra,pgsql as upstream package sources. With node_repo_modules: local, the local repository is the only package source. To permit upstream repositories as well, use local,node,infra,pgsql.

Hybrid installation

If the environment has Internet access, you can combine local and upstream package sources. Use the offline package as the initial repository. Then download missing packages from upstream.

For example, the v4.5.0 EL 9 package targets Rocky Linux 9.8. If you use Rocky Linux 9.6, run make repo-build before deployment to download the packages required for 9.6. This hybrid method requires Internet access to the upstream repositories.

Making Offline Packages

To build a package for another operating system, use the cache.yml playbook.

1. Select an online node with the exact operating system version and architecture of the offline nodes.
2. Run ./configure -c rich and complete an online installation with the rich template.
3. Make sure that the target INFRA node has a local repository at /www/pigsty.
4. If the repository is absent, run ./infra.yml -t repo against that node first.
5. From ~/pigsty, run ./cache.yml -l <infra-host> to build and fetch the package from one INFRA node.
6. Copy the package to the offline environment with FTP, SCP, or a USB device.
7. Use bootstrap to extract the package.

The default artifact path is ~/pigsty/dist/${version}/pigsty-pkg-${version}.${os}.${arch}.tgz. You can override these defaults with extra variables:

Paid services supply tested offline packages for specific operating system major and minor versions (¥200).

Bootstrap

Pigsty uses Ansible to run playbooks. The bootstrap script installs Ansible and prepares the required package repositories:

./bootstrap       # Ensure ansible is correctly installed (if offline package exists, use offline installation and extract first)

Run bootstrap in these cases:

• You downloaded or cloned the source manually and Ansible is absent.
• You need to extract an offline package and install Ansible from it.

By default, the script looks for /tmp/pkg.tgz. Use -p to specify a different package path. If the package exists, the script extracts it and installs Ansible from the local repository. If the package is absent, the script attempts an online Ansible installation. If that installation fails, install Ansible manually.

./bootstrap -k # or --keep

8 - Slim Installation

Use Slim Installation to deploy PostgreSQL without the monitoring infrastructure. It installs ETCD, PGSQL, and part of NODE. It does not install INFRA, monitoring services, or a local software repository.

Overview

1. Download Pigsty and enter the source directory.
2. Select the slim configuration template with ./configure -g -c slim.
3. Run ./slim.yml instead of ./deploy.yml.

curl https://repo.pigsty.io/get | bash
cd ~/pigsty
./configure -g -c slim
./slim.yml

demo/install-slim.cast — /demo/install-slim.cast

Description

Slim Installation configures these components:

You can disable all optional components through the configuration. Patroni and etcd remain required.

Without INFRA, Nginx does not serve a local software repository to other nodes. Thus, offline Slim Installation supports only one node.

Configuration

The conf/slim.yml template defines this single-node deployment:

---
#==============================================================#
# File      :   slim.yml
# Desc      :   Pigsty slim installation config template
# Ctime     :   2020-05-22
# Mtime     :   2025-12-28
# Docs      :   https://pigsty.io/docs/conf/slim
# License   :   Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright :   2018-2026  Ruohang Feng / Vonng ([email protected])
#==============================================================#

# This is the config template for slim / minimal installation
# No monitoring & infra will be installed, just raw postgresql
#
# Usage:
#   curl https://repo.pigsty.io/get | bash
#   ./configure -c slim
#   ./slim.yml

all:
  children:

    etcd: # dcs service for postgres/patroni ha consensus
      hosts: # 1 node for testing, 3 or 5 for production
        10.10.10.10: { etcd_seq: 1 }  # etcd_seq required
        #10.10.10.11: { etcd_seq: 2 }  # assign from 1 ~ n
        #10.10.10.12: { etcd_seq: 3 }  # three-member cluster keeps an odd voter count
      vars: # cluster level parameter override roles/etcd
        etcd_cluster: etcd  # mark etcd cluster name etcd

    #----------------------------------------------#
    # PostgreSQL Cluster
    #----------------------------------------------#
    pg-meta:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary }
        #10.10.10.11: { pg_seq: 2, pg_role: replica } # you can add more!
        #10.10.10.12: { pg_seq: 3, pg_role: replica, pg_offline_query: true }
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }
        pg_databases:
          - { name: meta, baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ vector ]}
        pg_hba_rules:   # https://pigsty.io/docs/pgsql/config/hba
          - { user: all ,db: all ,addr: intra ,auth: pwd ,title: 'everyone intranet access with password' ,order: 800 }
        pg_crontab:     # https://pigsty.io/docs/pgsql/admin/crontab
          - '00 01 * * * /pg/bin/pg-backup full'

  vars:
    version: v4.5.0                   # pigsty version string
    admin_ip: 10.10.10.10             # admin node ip address
    region: default                   # upstream mirror region: default,china,europe
    nodename_overwrite: false           # do not overwrite node hostname on single node mode
    node_repo_modules: node,infra,pgsql # add these repos directly to the singleton node
    node_tune: oltp                     # node tuning specs: oltp,olap,tiny,crit
    pg_conf: oltp.yml                   # pgsql tuning specs: {oltp,olap,tiny,crit}.yml
    pg_version: 18                      # Default PostgreSQL Major Version is 18
    pg_packages: [ pgsql-main, pgsql-common ]   # pg kernel and common utils
    #pg_extensions: [ pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-olap ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl]

    #----------------------------------------------#
    # PASSWORD : https://pigsty.io/docs/setup/security/
    #----------------------------------------------#
    grafana_admin_password: pigsty
    grafana_view_password: DBUser.Viewer
    pg_admin_password: DBUser.DBA
    pg_monitor_password: DBUser.Monitor
    pg_replication_password: DBUser.Replicator
    patroni_password: Patroni.API
    haproxy_admin_password: pigsty
    minio_secret_key: S3User.MinIO
    etcd_root_password: Etcd.Root
...

Deployment

Use the slim.yml playbook for deployment. Run it from the Pigsty source directory:

./slim.yml

HA Cluster

To deploy an HA cluster, add nodes to both the etcd and pg-meta groups. This example uses three nodes:

all:
  children:
    etcd:
      hosts:
        10.10.10.10: { etcd_seq: 1 }
        10.10.10.11: { etcd_seq: 2 }  # <-- New
        10.10.10.12: { etcd_seq: 3 }  # <-- New

    pg-meta:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary }
        10.10.10.11: { pg_seq: 2, pg_role: replica } # <-- New
        10.10.10.12: { pg_seq: 3, pg_role: replica } # <-- New
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }
        pg_databases:
          - { name: meta, baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ vector ]}
        pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # full backup daily at 1am
  vars:
    # omitted ……

9 - Security Recommendations

The default configuration supports local demonstrations and development on a trusted intranet. If other hosts can reach the deployment, examine the credentials, network access, and sensitive files.

For production, also review the Security Model, Compliance, and Security Considerations.

Passwords

Pigsty publishes its default credentials in the source code and documentation. Do not use these credentials in production.

Run the configuration wizard with -g to generate random passwords:

./configure -g

The wizard replaces the built-in parameters and example credentials that it recognizes. It does not replace these credentials:

• The pgBackRest cipher_pass.
• Silo user passwords and selected example passwords in ha/safe.
• Database, object-storage, or application credentials that you added yourself.

After generation, examine pigsty.yml. Replace every credential that the wizard did not change.

The wizard prints generated passwords to the terminal. Protect terminal records and automation logs that contain these passwords. See the Default Credentials Checklist for the complete scope.

Firewall

The default value of node_firewall_mode is zone. This mode trusts the intranet defined by node_firewall_intranet. It restricts access to ports from public networks.

For production, normally remove port 5432 from the demonstration configuration. If applications require direct database access, permit only their source addresses. Apply these restrictions in the cloud security group, host firewall, and PostgreSQL HBA rules.

Make sure that the intranet definition matches your trusted network. The default RFC 1918 address ranges can include networks that you do not trust. Do not automatically trust office networks, container networks, or other tenant networks.

Files

These files and directories contain sensitive information:

Restrict access to the administration node and configuration repository. Do not commit complete inventories or private keys to public repositories. Keep controlled backups of the CA private key and required configuration.

Related Documentation

• Security and Compliance introduces the security model.
• Authentication explains HBA rules, passwords, and client certificates.
• Encrypted Communication explains the CA, TLS, and server verification.
• Production Security Considerations supplies the complete deployment checklist.