This is the multi-page printable view of this section. .
Configuration Templates
- 1: meta
- 2: rich
- 3: slim
- 4: fat
- 5: infra
- 6: vibe
- 7: docker
- 8: pgsql
- 9: pg19
- 10: mssql
- 11: polar
- 12: ivory
- 13: agens
- 14: pgedge
- 15: mysql
- 16: pgtde
- 17: oriole
- 18: PostgreSQL Mongo Mode
- 19: ha/simu
- 20: ha/octo
- 21: ha/full
- 22: ha/safe
- 23: ha/trio
- 24: ha/dual
- 25: ha/citus
- 26: demo/bare
- 27: demo/el
- 28: demo/debian
- 29: demo/demo
- 30: demo/kernel
- 31: demo/minio
- 32: demo/redis
- 33: demo/kafka
- 34: demo/mysql
- 35: build/oss
- 36: build/dev
- 37: demo/remote
- 38: demo/saas
- 39: demo/wool
Use -c with configure to select a template. Its value is a path relative to conf/ without the .yml suffix. If omitted, Pigsty uses the default meta template.
| Category | Templates |
|---|---|
| Solo Templates | meta, rich, fat, slim, infra, vibe, docker |
| Kernel Templates | pgsql, pg19, mssql, polar, ivory, agens, pgedge, mysql (OpenHalo), mongo, pgtde, oriole |
| HA Templates | ha/simu, ha/octo, ha/citus, ha/full, ha/safe, ha/trio, ha/dual |
| App Templates | supabase, app/odoo, app/dify, app/insforge, app/hindsight, app/electric, app/maybe, app/teable, app/mattermost, app/registry, app/immich, app/jumpserver |
| Misc Templates | demo/bare, demo/el, demo/debian, demo/demo, demo/kernel, demo/redis, demo/minio, demo/kafka, demo/mysql (native MySQL pilot), demo/remote, demo/saas, demo/wool, build/oss, build/dev |
1 - meta
The meta configuration template is Pigsty’s default template, designed to fulfill Pigsty’s core functionality—deploying PostgreSQL—on a single node.
To maximize compatibility, meta installs only the minimum required software set to ensure it runs across all operating system distributions and architectures.
Overview
- Config Name:
meta - Node Count: Single node
- Description: Default single-node installation template with extensive configuration parameter descriptions and minimum required feature set.
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta,slim,fat
Usage: This is the default config template, so there’s no need to specify -c meta explicitly during configure:
For example, if you want to install PostgreSQL 16 rather than the default 18, you can use the -v arg in configure:
Content
Source: pigsty/conf/meta.yml
Explanation
The meta template is Pigsty’s default getting-started configuration, designed for quick onboarding.
Use Cases:
- First-time Pigsty users
- Quick deployment in development and testing environments
- Small production environments running on a single machine
- As a base template for more complex deployments
Key Features:
- Online installation mode without building local software repository (
repo_enabled: false) - Default installs PostgreSQL 18 with
postgisandpgvectorextensions - Includes complete observability infrastructure (Grafana, VictoriaMetrics, VictoriaLogs, etc.)
- Preconfigured Docker and pgAdmin application examples
- Silo backup storage disabled by default, can be enabled as needed
Notes:
- Default passwords are sample passwords; must be changed for production environments
- Single-node etcd has no high availability guarantee, suitable for development and testing
- If you need to build a local software repository, use the
richtemplate
2 - rich
The rich configuration template is an enhanced version of meta, designed for users who need to experience complete functionality.
If you want to build a local software repository, use Silo for backup storage, run Docker applications, or need preconfigured business databases, use this template.
Overview
- Config Name:
rich - Node Count: Single node
- Description: Feature-rich single-node configuration, adding local software repository, Silo backup, complete extensions, Docker application examples on top of
meta - OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta,slim,fat
This template’s main enhancements over meta:
- Builds local software repository (
repo_enabled: true), downloads all PG extensions - Enables single-node Silo as PostgreSQL backup storage
- Preinstalls TimescaleDB, pgvector, pg_wait_sampling and other extensions
- Includes detailed user/database/service definition comment examples
- Adds Redis primary-replica instance example
- Preconfigures pg-test three-node HA cluster configuration stub
Usage:
Content
Source: pigsty/conf/rich.yml
Explanation
The rich template is Pigsty’s complete functionality showcase configuration, suitable for users who want to deeply experience all features.
Use Cases:
- Offline environments requiring local software repository
- Environments needing Silo as PostgreSQL backup storage
- Pre-planning multiple business databases and users
- Running Docker applications (pgAdmin, Bytebase, etc.)
- Learners wanting to understand complete configuration parameter usage
Main Differences from meta:
- Enables local software repository building (
repo_enabled: true) - Enables Silo backup storage (compatibility preset
pgbackrest_method: minio) - Preinstalls TimescaleDB, pg_wait_sampling and other additional extensions
- Includes detailed parameter comments for understanding configuration meanings
- Preconfigures HA cluster stub configuration (pg-test)
Notes:
- Some extensions unavailable on ARM64 architecture, adjust as needed
- Building local software repository requires longer time and larger disk space
- Default passwords are sample passwords, must be changed for production
3 - slim
The slim configuration template provides minimal installation capability, installing a PostgreSQL high-availability cluster directly from the internet without deploying Infra monitoring infrastructure.
When you only need an available database instance without the monitoring system, consider using the Slim Installation mode.
Overview
- Config Name:
slim - Node Count: Single node
- Description: Minimal installation template without monitoring infrastructure, installs PostgreSQL directly
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/slim.yml
Explanation
The slim template is Pigsty’s minimal installation configuration, designed for quick deployment of bare PostgreSQL clusters.
Use Cases:
- Only need PostgreSQL database, no monitoring system required
- Resource-limited small servers or edge devices
- Quick deployment of temporary test databases
- Already have monitoring system, only need PostgreSQL HA cluster
Key Features:
- Uses
slim.ymlplaybook instead ofdeploy.ymlfor installation - Installs software directly from internet, no local software repository
- Retains core PostgreSQL HA capability (Patroni + etcd + HAProxy)
- Minimized package downloads, faster installation
- Default uses PostgreSQL 18
Differences from meta:
slimuses dedicatedslim.ymlplaybook, skips Infra module installation- Faster installation, less resource usage
- Suitable for “just need a database” scenarios
Notes:
4 - fat
The fat configuration template is Pigsty’s Feature-All-Test template, installing all extension plugins on a single node and building a local software repository containing all extensions for PostgreSQL 14-18 (five major versions).
This is a full-featured configuration for testing and development, suitable for scenarios requiring complete software package cache or testing all extensions.
Overview
- Config Name:
fat - Node Count: Single node
- Description: Feature-All-Test template, installs all extensions, builds local repo with PG 14-18 all versions
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta,slim,fat
Usage:
To specify a particular PostgreSQL version:
Content
Source: pigsty/conf/fat.yml
Explanation
The fat template is Pigsty’s full-featured test configuration, designed for completeness testing and offline package building.
Key Features:
- All Extensions: Installs all categorized extension packages for PostgreSQL 18
- Multi-version Repository: Local repo contains all five major versions of PostgreSQL 14-18
- Complete Component Stack: Includes Silo backup, Docker applications, VIP, etc.
- Enterprise Components: Includes Kafka, PolarDB, IvorySQL, TigerBeetle, etc.
Repository Contents:
| Category | Description |
|---|---|
| PostgreSQL 14-18 | Five major versions’ kernels and all extensions |
| Extension Categories | time, gis, rag, fts, olap, feat, lang, type, util, func, admin, stat, sec, fdw, sim, etl |
| Enterprise Components | kafka-stack, Java Runtime, Sealos, TigerBeetle |
| Database Kernels | PolarDB, IvorySQL |
Differences from rich:
fatcontains all five versions of PostgreSQL 14-18,richonly contains current default versionfatcontains additional enterprise components (Kafka, PolarDB, IvorySQL, etc.)fatrequires larger disk space and longer build time
Use Cases:
- Pigsty development testing and feature validation
- Building complete multi-version offline software packages
- Testing all extension compatibility scenarios
- Enterprise environments pre-caching all software packages
Notes:
- Requires large disk space (100GB+ recommended) for storing all packages
- Building local software repository requires longer time
- Some extensions unavailable on ARM64 architecture
- Default passwords are sample passwords, must be changed for production
5 - infra
The infra configuration template only deploys Pigsty’s observability infrastructure components (VictoriaMetrics/Grafana/VictoriaLogs/Nginx, etc.), without PostgreSQL and etcd.
Suitable for scenarios requiring a standalone monitoring stack, such as monitoring external PostgreSQL/RDS instances or other data sources.
Overview
- Config Name:
infra - Node Count: Single or multiple nodes
- Description: Only installs observability infrastructure, without PostgreSQL and etcd
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/infra.yml
Explanation
The infra template is Pigsty’s pure monitoring stack configuration, designed for standalone deployment of observability infrastructure.
Use Cases:
- Monitoring external PostgreSQL instances (RDS, self-hosted, etc.)
- Need standalone monitoring/alerting platform
- Already have PostgreSQL clusters, only need to add monitoring
- As a central console for multi-cluster monitoring
Included Components:
- VictoriaMetrics: Time series database for storing metrics
- VictoriaLogs: Log aggregation system
- VictoriaTraces: Distributed tracing system
- Grafana: Visualization dashboards
- Alertmanager: Alert management
- Nginx: Reverse proxy and web entry
Not Included:
- PostgreSQL database cluster
- etcd distributed coordination service
- Silo object storage
Monitoring External Instances:
After configuration, add monitoring for external PostgreSQL instances via the pgsql-monitor.yml playbook:
Notes:
6 - vibe
The vibe config template provides a ready-to-use AI coding sandbox, integrating Code-Server (Web VS Code), JupyterLab, Claude Code observability, Codex CLI, JuiceFS distributed filesystem, and a feature-rich PostgreSQL database.
Overview
- Config Name:
vibe - Node Count: Single node
- Description: VIBE AI coding sandbox with Code-Server + JupyterLab + Claude Code + Codex CLI + JuiceFS + PostgreSQL
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/vibe.yml
Explanation
The vibe template is an AI-era Web coding sandbox, enabling development, data analysis, AI app building all in browser.
Core Components:
| Component | Description | Access Method |
|---|---|---|
| Code-Server | Web version of VS Code, full-featured code editor | http://<ip>/code |
| JupyterLab | Interactive data science notebook, Python/SQL | http://<ip>/jupyter |
| Claude Code | AI coding runtime and observability entrypoint (claude_env customizable) |
Terminal / Dashboard |
| Codex CLI | OpenAI agentic coding CLI; VIBE installs it but does not manage its configuration | Terminal |
| JuiceFS | PostgreSQL-based distributed filesystem | Mount point /fs |
| PostgreSQL 18 | Feature-rich database with pg18-main + categorized extension package groups |
Port 5432 |
Node tools explicitly installed by this template (node_packages):
openssh-server,juicefs,restic,rcloneuv,opencode,golangasciinema,tmux
PostgreSQL Extensions:
This template installs PostgreSQL 18 extension groups by category:
By default, the meta database enables postgis, timescaledb, and vector; other extensions can be enabled as needed.
VIBE Module Components
The VIBE module provides AI coding sandbox capability; vibe.yml explicitly enables Code-Server and Jupyter and installs Claude Code and Codex CLI by default.
Code-Server: VS Code in browser
- Full VS Code functionality, extension support
- HTTPS access via Nginx reverse proxy
- Supports Open VSX and Microsoft extension marketplaces
- Explicit template params:
code_enabled,code_password - Optional params:
code_port,code_data,code_gallery
JupyterLab: Interactive computing environment
- Python/SQL/Markdown notebook support
- Pre-configured Python venv with data science libraries
- HTTPS access via Nginx reverse proxy
- Explicit template params:
jupyter_enabled,jupyter_password - Optional params:
jupyter_port,jupyter_data,jupyter_venv
Claude Code: AI coding assistant runtime
- Uses module default behavior to bootstrap Claude runtime
- Supports endpoint/API key overrides through
claude_env - Provides
claude-codedashboard for usage monitoring
Codex CLI: AI coding assistant
- Controlled by
codex_enabled, which defaults totrue - VIBE installs
@openai/codexonly; it does not write Codex configuration or connect Codex to the Claude Code dashboard
JuiceFS Filesystem
This template uses JuiceFS for distributed filesystem capability, with a special feature: both metadata and data stored in PostgreSQL.
Architecture Features:
- Metadata Engine: Uses PostgreSQL for filesystem metadata storage
- Data Storage: Uses PostgreSQL Large Object for file data storage
- Mount Point: Default mount at
/fs(controlled byjuice_instances.jfs.path) - Monitoring Port:
9567provides Prometheus metrics
Use Cases:
- Persistent storage for code projects
- Working directory for Jupyter Notebooks
- Storage for AI models and datasets
- File sharing across instances (when scaled to multiple nodes)
Config Example:
Deployment Steps
Access Methods
After deployment, access via browser:
Use Cases
- AI App Development: Build RAG, Agent, LLM applications
- Data Science: Use JupyterLab for data analysis and visualization
- Remote Development: Setup Web IDE environment on cloud servers
- Teaching Demos: Provide consistent dev environment for students
- Rapid Prototyping: Quickly validate ideas without local env setup
- Claude Code Observability: Monitor AI coding assistant usage
Notes
- Must change passwords:
code_passwordandjupyter_passworddefaults are for testing only - Jupyter boundary: The template listens on
0.0.0.0:8888, allows any Origin, disables XSRF checks, and relies on the token by default; restrict the port and portal sources and never expose it directly to the Internet - Network security: This template exposes
5432(node_firewall_public_port) and includesaddr: worldHBA by default; remove those public paths for production and add portal Basic Auth when appropriate - Resource requirements: Recommend at least 2 cores 4GB memory, SSD disk
- Simplified architecture: This template disables Patroni, PgBouncer etc HA components, suitable for single-node dev env
- Claude API: Using Claude Code requires configuring API key in
claude_env
7 - docker
The docker configuration template runs Pigsty inside a Docker container and provides a minimal single-node stack for infrastructure and PostgreSQL.
For full workflow details, see Docker Deployment.
Overview
- Config Name:
docker - Node Count: Single node (container runtime)
- Description: Quick-start container template using
127.0.0.1and trimmed system capabilities for Docker scenarios - OS Distro: Container image runtime (official Pigsty Docker image recommended)
- OS Arch:
x86_64,aarch64 - Related:
meta,vibe
Usage:
Content
Source: pigsty/conf/docker.yml
Explanation
The docker template is optimized for development and validation inside containers.
Key Features:
- Disables local repo build (
repo_enabled: false) to avoid extra build overhead in containers - Simplifies node behavior by disabling NTP, kernel module loading, and
/etc/hostsrewrite - Uses PostgreSQL 18 by default with a broad preset extension package bundle (
pg18-*) - Allows password access from both
intraandworldranges inpg_hba_rulesfor fast testing - Keeps optional capabilities (Code-Server, Jupyter, JuiceFS, Claude CLI) as commented settings
Notes:
- This template is designed for development and demos; tighten
pg_hba_rulesand password policy for production - Mount
/datain the container runtime to persist PostgreSQL and component data
8 - pgsql
The pgsql configuration template uses the native PostgreSQL kernel, Pigsty’s default database kernel, with stable support for PostgreSQL 14 to 18. The current configure also accepts version 19, but PG19 remains Beta; use the dedicated pg19 template for evaluation.
Overview
- Config Name:
pgsql - Node Count: Single node
- Description: Native PostgreSQL kernel configuration template
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
To specify a non-default PostgreSQL version (e.g., 16):
Content
Source: pigsty/conf/pgsql.yml
Explanation
The pgsql template is Pigsty’s standard kernel configuration, using community-native PostgreSQL.
Version Support:
- PostgreSQL 18 (default)
- PostgreSQL 17, 16, 15, 14
- PostgreSQL 19 Beta (evaluation; use
./configure -c pg19)
Use Cases:
- Need to use the latest PostgreSQL features
- Need the widest extension support
- Standard production environment deployment
- Same functionality as
metatemplate, explicitly declaring native kernel usage
Differences from meta:
pgsqltemplate explicitly declares using native PostgreSQL kernel- Suitable for scenarios needing clear distinction between different kernel types
9 - pg19
pg19 is the single-node PostgreSQL 19 Beta evaluation template. It follows the meta topology, enables the beta repository, and limits the local repository’s additional cache to core PGSQL packages without preinstalling extensions.
Overview
- Config Name:
pg19 - Node Count: Single node
- PostgreSQL Version:
19Beta - Use Cases: New-version evaluation and compatibility testing
- Related:
meta,pgsql
Usage:
Content
Source: pigsty/conf/pg19.yml
Explanation
Important defaults and limitations:
node_repo_modules: node,infra,pgsql,betaobtains PG19 packages from the PGDG Beta repositoryrepo_extra_packages: [pgsql-core]limits the local repository’s additional cache to core PGSQL packages; instances still use the role’s defaultpgsql-main pgsql-commoninstallation setpg_extensions: []installs no extension packagespgbackrest_enabled: trueandpgbackrest_exporter_enabled: true;pg-metaretains its daily 01:00 full-backup job- INFRA, ETCD, PGSQL, and optional pgAdmin remain available for a single-node evaluation
This is a Beta evaluation configuration, not a production template. Do not treat -v 19 on an ordinary template as a production-ready PG19 deployment; validate extension compatibility, backup and recovery, and upgrade procedures separately.
10 - mssql
The mssql configuration template uses a PostgreSQL 17-compatible Babelfish kernel instead of native PostgreSQL, providing Microsoft SQL Server wire protocol (TDS) and T-SQL syntax compatibility. The current template is pinned to pg_version: 17; configure does not apply -v overrides to this fixed-kernel template.
Since Pigsty v4.2, Babelfish is built directly by Pigsty, no longer using the WiltonDB repository, and is available on all supported Linux platforms.
For the complete tutorial, see: Babelfish (MSSQL) Kernel Guide
Overview
- Config Name:
mssql - Node Count: Single node
- Description: Babelfish (PG17) configuration template with SQL Server protocol compatibility
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/mssql.yml
Explanation
The mssql template allows you to use SQL Server Management Studio (SSMS) or other SQL Server client tools to connect to PostgreSQL (through Babelfish protocol compatibility).
Key Features:
- Uses TDS protocol (port 1433), compatible with SQL Server clients
- Supports T-SQL syntax, low migration cost
- Retains PostgreSQL’s ACID properties and extension ecosystem (the current template uses PG17)
- Supports
multi-dbandsingle-dbmigration modes - Default package set:
babelfish + pgsql-common + sqlcmd - Creates
uuid-ossp,babelfishpg_common,babelfishpg_tsql,babelfishpg_tds, andbabelfishpg_moneyby default - v4.2.0 adds full mainstream platform coverage (EL 8/9/10, Debian 12/13, Ubuntu 22/24/26;
x86_64/aarch64)
Connection Methods:
Use Cases:
- Migrating from SQL Server to PostgreSQL
- Applications needing to support both SQL Server and PostgreSQL clients
- Leveraging PostgreSQL ecosystem while maintaining T-SQL compatibility
Notes:
- The current
mssqltemplate is pinned to a PostgreSQL 17-compatible kernel; do not rely on-vto switch its major version - Default migration mode is
multi-db(babelfishpg_tsql.migration_mode), configurable tosingle-dbwhen needed - Some T-SQL syntax may have compatibility differences, refer to Babelfish compatibility documentation
- Must use
md5authentication method (notscram-sha-256)
11 - polar
The polar configuration template uses Alibaba Cloud’s PolarDB for PostgreSQL database kernel instead of native PostgreSQL, providing “cloud-native” Aurora-style storage-compute separation capability.
For the complete tutorial, see: PolarDB for PostgreSQL (POLAR) Kernel Guide. For kernel differences and version references, see the PGSQL kernel overview.
Overview
- Config Name:
polar - Node Count: Single node
- Description: Uses PolarDB for PostgreSQL kernel
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/polar.yml
Explanation
The polar template uses Alibaba Cloud’s open-source PolarDB for PostgreSQL kernel, providing cloud-native database capabilities.
Key Features:
- Storage-compute separation architecture, compute and storage nodes can scale independently
- Supports one-write-multiple-read, read replicas scale in seconds
- Compatible with PostgreSQL ecosystem, maintains SQL compatibility
- Supports shared storage scenarios, suitable for cloud environment deployment
- Default PolarDB kernel path is
/usr/polar-17 - Available extensions follow the PolarDB 17 kernel catalog. Common extensions include
pgaudit,pg_partman,pg_profile,pg_repack,pg_stat_kcache,pg_cron, andpg_hint_plan
Use Cases:
- Cloud-native scenarios requiring storage-compute separation architecture
- Read-heavy write-light workloads
- Scenarios requiring quick scaling of read replicas
- Test environments for evaluating PolarDB features
Notes:
- PolarDB is now based on PostgreSQL 17
- Replication user requires superuser privileges (different from native PostgreSQL)
- Some PostgreSQL extensions may have compatibility issues
- The current template provides packages for both
x86_64andaarch64
12 - ivory
The ivory configuration template uses Highgo’s IvorySQL database kernel instead of native PostgreSQL, providing Oracle syntax and PL/SQL compatibility.
For the complete tutorial, see: IvorySQL (Oracle Compatible) Kernel Guide
Overview
- Config Name:
ivory - Node Count: Single node
- Description: Uses IvorySQL Oracle-compatible kernel
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/ivory.yml
Explanation
The ivory template uses Highgo’s open-source IvorySQL kernel, providing Oracle database compatibility.
Key Features:
- Supports Oracle PL/SQL syntax
- Compatible with Oracle data types (NUMBER, VARCHAR2, etc.)
- Supports Oracle-style packages
- Retains all standard PostgreSQL functionality
Use Cases:
- Migrating from Oracle to PostgreSQL
- Applications needing both Oracle and PostgreSQL syntax support
- Leveraging PostgreSQL ecosystem while maintaining PL/SQL compatibility
- Test environments for evaluating IvorySQL features
Notes:
- IvorySQL 5 is based on PostgreSQL 18
- Using
liboracle_parserrequires loading intoshared_preload_libraries pgbackrestmay have checksum issues in Oracle-compatible mode, PITR capability is limited- The current package matrix covers EL 8/9/10, Debian 12/13, Ubuntu 22/24/26, and both architectures
13 - agens
The agens configuration template replaces native PostgreSQL with the AgensGraph kernel and enables property-graph modeling plus Cypher queries.
For the full guide, see: AgensGraph kernel guide
Overview
- Config name:
agens - Node count: Single node
- Description: AgensGraph (PG17) graph database kernel template
- Supported OS:
el8,el9,el10,d12,d13,u22,u24,u26 - Supported arch:
x86_64,aarch64 - Related templates:
meta,pgsql
Enable with:
Template Content
Source: pigsty/conf/agens.yml
Notes
The agens template enables pg_mode: agens in the pg-meta cluster and installs the agensgraph kernel package instead of standard PostgreSQL.
Key features:
- Property graph model support (Vertex / Edge)
- Cypher query syntax, can be combined with SQL
- Compatible with PostgreSQL ecosystem and standard operations
- Based on PostgreSQL 17-compatible kernel by default
Typical use cases:
- Graph relationship analysis and path queries
- Social graph, risk linkage, knowledge graph scenarios
- Workloads requiring graph queries within PostgreSQL operations
Caveats:
- Current AgensGraph template is pinned to
pg_version: 17 - Default topology is single-node for quick validation; production should extend with HA topology planning
- Graph schema and Cypher semantics should follow official AgensGraph docs
14 - pgedge
The pgedge configuration template replaces native PostgreSQL with the pgEdge kernel and provides distributed, multi-master capabilities for edge deployments.
For the full guide, see: pgEdge kernel guide. For kernel differences and version references, see the PGSQL kernel overview.
Overview
- Config name:
pgedge - Node count: Single node
- Description: pgEdge (PG18) distributed kernel template
- Supported OS:
d12,d13,u22,u24,u26for PG18 packages. For EL/RPM platforms, check current PGSQL repository availability forpgedge_18. - Supported arch:
x86_64,aarch64 - Related templates:
meta,pgsql
Enable with:
Template Content
Source: pigsty/conf/pgedge.yml
Notes
The pgedge template enables pg_mode: pgedge in pg-meta and pre-installs pgEdge core extensions for logical replication and edge distribution.
Key features:
- Uses the
pgedgekernel package (PG15/16/17/18 compatible, default PG18) - Bundles
spock,snowflake, andlolorin thepgedge-$vkernel package and creates them in themetadatabase by default - Preloads
spockandlolorfor multi-master setup readiness - Keeps Pigsty standard backup, monitoring, and operations workflow
Typical use cases:
- Multi-region edge deployment with nearby writes
- Multi-master logical replication with conflict handling
- Single-node validation before distributed rollout
Caveats:
- Current template is for single-node kernel validation; production multi-master needs explicit topology and replication strategy planning
- Default is
pg_version: 18; keep consistent with target cluster versions - Evaluate latency and conflict policy before cross-region replication
15 - mysql
The mysql configuration template uses OpenHalo database kernel instead of native PostgreSQL, providing MySQL wire protocol and SQL syntax compatibility.
Overview
- Config Name:
mysql - Node Count: Single node
- Description: OpenHalo MySQL-compatible kernel configuration
- OS Distro: EL 8/9/10, Debian 12/13, Ubuntu 22/24/26
- OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/mysql.yml
Explanation
The mysql template uses the OpenHalo kernel, allowing you to connect to PostgreSQL using MySQL client tools.
Key Features:
- Uses MySQL protocol (port 3306), compatible with MySQL clients
- Supports a subset of MySQL SQL syntax
- Retains PostgreSQL’s ACID properties and storage engine
- Supports both PostgreSQL and MySQL protocol connections simultaneously
Connection Methods:
Use Cases:
- Migrating from MySQL to PostgreSQL
- Applications needing to support both MySQL and PostgreSQL clients
- Leveraging PostgreSQL ecosystem while maintaining MySQL compatibility
Notes:
- OpenHalo is based on PostgreSQL 14, does not support higher version features
- Some MySQL syntax may have compatibility differences
- The current
openhalopackage alias covers Pigsty’s supported Linux platforms on both architectures; actual installation still depends on the target platform’s repository index
16 - pgtde
The pgtde configuration template uses Percona PostgreSQL database kernel, providing Transparent Data Encryption (TDE) capability.
Overview
- Config Name:
pgtde - Node Count: Single node
- Description: Percona PostgreSQL transparent data encryption configuration
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/pgtde.yml
Explanation
The pgtde template selects pg_mode: pgtde and installs the pgtde package
alias. Pigsty links the private /usr/pgtde-$v prefix (currently
/usr/pgtde-18) to its stable /usr/pgsql entry point.
Key Features:
- Transparent Data Encryption: Data automatically encrypted on disk, transparent to applications
- Key Management: Supports local keys and external Key Management Systems (KMS)
- Table-level Encryption: Selectively encrypt sensitive tables
- Full Compatibility: Fully compatible with native PostgreSQL
Use Cases:
- Meeting data security compliance requirements (e.g., PCI-DSS, HIPAA)
- Storing sensitive data (e.g., personal information, financial data)
- Scenarios requiring data-at-rest encryption
- Enterprise environments with strict data security requirements
Usage:
Notes:
- Percona PostgreSQL is based on PostgreSQL 18
- Encryption brings some performance overhead (typically 5-15%)
- Encryption keys must be properly managed
- Both
x86_64andaarch64packages are available on the listed distributions
17 - oriole
The oriole configuration template uses OrioleDB storage engine instead of PostgreSQL’s default Heap storage, providing bloat-free, high-performance OLTP capability.
Overview
- Config Name:
oriole - Node Count: Single node
- Description: OrioleDB bloat-free storage engine configuration
- PostgreSQL Major:
16,17, or18 - OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
Content
Source: pigsty/conf/oriole.yml
Explanation
The oriole template uses OrioleDB storage engine, fundamentally solving PostgreSQL table bloat problems.
Key Features:
- Bloat-free Design: Uses UNDO logs instead of Multi-Version Concurrency Control (MVCC)
- No VACUUM Required: Eliminates performance jitter from autovacuum
- Row-level WAL: More efficient logging and replication
- Compressed Storage: Built-in data compression, reduces storage space
Use Cases:
- High-frequency update OLTP workloads
- Applications sensitive to write latency
- Need for stable response times (eliminates VACUUM impact)
- Large tables with frequent updates causing bloat
Usage:
Notes:
- OrioleDB supports PostgreSQL 16, 17, and 18; the template defaults to PG18, and you can select a major version with
-v 16,-v 17, or-v 18 - Need to add
orioledbtoshared_preload_libraries - Some PostgreSQL features may not be fully supported
- Use the matching OrioleDB packages for the selected PostgreSQL major and OS architecture
18 - PostgreSQL Mongo Mode
The mongo configuration template is a PostgreSQL deployment mode, not an independent Pigsty module. It combines:
- PostgreSQL 18 managed by the standard
PGSQLmodule - The
documentdbextension and its required preload libraries - A stateless FerretDB proxy deployed with Pigsty’s Docker APP workflow
All data, high availability, backup, monitoring, and lifecycle management remain PostgreSQL responsibilities. FerretDB only provides the MongoDB wire-compatible endpoint.
Quick Start
The default template is a single-node deployment on 10.10.10.10. FerretDB listens on loopback by default.
Install mongosh separately if it is not already available, or use another MongoDB-compatible client.
The dedicated mongod PostgreSQL login is declared by the template. FerretDB authentication is enabled, but MongoDB authorization roles are not implemented; PostgreSQL remains the security boundary.
Architecture
| Layer | Implementation | Responsibility |
|---|---|---|
| Data | PostgreSQL + DocumentDB | Durable storage, transactions, HA, PITR, ACL, monitoring |
| Protocol | FerretDB Docker APP | Stateless MongoDB wire compatibility |
| Access | 127.0.0.1:27017 by default |
Local MongoDB client endpoint |
The container connects to Pigsty’s local primary service on port 5436 through host.docker.internal. The default Mongo endpoint is not exposed to the network; change FERRETDB_BIND_ADDR only when remote access is required.
Configuration
Source: pigsty/conf/mongo.yml
FerretDB settings are ordinary APP overrides under apps.ferretdb.conf:
Use the standard PostgreSQL parameters, playbooks, dashboards, and administration procedures for the backend cluster. There are no mongo_* inventory parameters or standalone mongo.yml playbook.
Optional HA Topology
The template contains a commented pg-mongo example for three PostgreSQL/FerretDB nodes. Uncomment that block and the two additional etcd members when needed.
In HA mode, each FerretDB container binds {{ inventory_hostname }}:27018; HAProxy exposes all three backends through the floating endpoint 10.10.10.4:27017 (mongo.pigsty). PostgreSQL failover is still handled by Patroni, while FerretDB remains stateless.
Notes
- The template includes development-friendly HBA examples; tighten them for production.
- Client-side MongoDB TLS is not enabled by default.
- Monitor the backend with the standard PostgreSQL and Docker dashboards; there is no separate FERRET module or dedicated module dashboard.
- Repeat an authenticated CRUD smoke test after upgrading FerretDB or DocumentDB.
19 - ha/simu
The ha/simu configuration template is a 20-node production environment simulation, requiring a powerful host machine to run.
Overview
- Config Name:
ha/simu - Node Count: 20 nodes,
pigsty/vagrant/spec/simu.rb - Description: 20-node production environment simulation, requires powerful host machine
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64
Usage:
Content
Source: pigsty/conf/ha/simu.yml
Explanation
The ha/simu template is a large-scale production environment simulation for testing and validating complex scenarios.
Architecture:
- 2-node HA INFRA (monitoring/alerting/Nginx/DNS)
- 5-node HA ETCD and MINIO (Silo, multi-disk)
- 2-node Proxy (HAProxy + Keepalived VIP)
- Multiple PostgreSQL clusters:
- pg-meta: 2-node HA
- pg-v14~v18: Single-node multi-version testing
- pg-pitr: Single-node PITR testing
- pg-test: 4-node HA
- pg-src/pg-dst: 3+2 node replication testing
- pg-citus: 10-node distributed cluster
- Multiple Redis modes: primary-replica, sentinel, cluster
Use Cases:
- Large-scale deployment testing and validation
- High availability failover drills
- Performance benchmarking
- New feature preview and evaluation
Notes:
- Requires powerful host machine (64GB+ RAM recommended)
- Uses Vagrant virtual machines for simulation
20 - ha/octo
ha/octo uses the first eight nodes from vagrant/spec/deci.rb to build a compact high-availability simulation. It exercises co-located modules, VIPs, remote backup, and larger membership counts. Do not use it directly as a production blueprint without reviewing capacity, security, and failure domains.
Overview
- Config name:
ha/octo - Node addresses:
10.10.10.10through10.10.10.17 - INFRA: 3 nodes; only the first builds and serves the local repository, while Docker can be installed separately on all three as noted in comments
- ETCD: 5 nodes on the last five hosts
- Object storage: one eight-node, single-drive cluster; the template does not override
minio_type, so both deployment and removal roles default to Silo; verify that value, the exact target, and data paths before removal pg-meta: 3-node PostgreSQL cluster with VIP10.10.10.2/24pg-test: 5-node PostgreSQL cluster whose final instance has theofflinerole, with VIP10.10.10.3/24- Backup: uses the object-storage repository through
sss.pigsty:9002and also retains a local repository
This template depends on fixed eight-node addresses and VIPs. For any other environment, update the host addresses, VIPs, interfaces, DNS, repository node, and every public example credential together.
Content
Source: pigsty/conf/ha/octo.yml
Explanation
- The three INFRA nodes and five etcd nodes are separate sets. The
pg-metaandpg-testPostgreSQL clusters are co-located with those two sets respectively. - Object storage spans all eight nodes and exposes
sss.pigstythrough Keepalived VIP10.10.10.9and HAProxy port9002. Silo is the current default engine, while the module and variables retainminio_*compatibility names. pg-metatakes one full backup daily.pg-testtakes a weekly full backup and incremental backups on the remaining days; both write to the encrypted S3 pgBackRest repository.- The two INFRA replicas with
repo_enabled: falsedo not build local repositories. Every node still installs packages from the first node’slocalrepository. - The database, Grafana, Patroni, HAProxy, Silo, and etcd passwords at the end of the template are suitable only for a disposable simulation and must all be rotated in real environments.
For a conventional minimal HA deployment, prefer ha/trio. For a larger full-scenario simulation, see ha/simu.
21 - ha/full
The ha/full configuration template is Pigsty’s recommended sandbox demonstration environment, deploying two PostgreSQL clusters across four nodes for testing and demonstrating various Pigsty capabilities.
Most Pigsty tutorials and examples are based on this template’s sandbox environment.
Overview
- Config Name:
ha/full - Node Count: Four nodes
- Description: Four-node complete feature demonstration environment with two PostgreSQL clusters, Silo, Redis, etc.
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
ha/trio,ha/safe,demo/demo
Usage:
After configuration, modify the IP addresses of the other three nodes.
Content
Source: pigsty/conf/ha/full.yml
Explanation
The ha/full template is Pigsty’s complete feature demonstration configuration, showcasing the collaboration of various components.
Components Overview:
| Component | Node Distribution | Description |
|---|---|---|
| INFRA | Node 1 | Monitoring/Alerting/Nginx/DNS |
| ETCD | Node 1 | DCS Service |
| Silo | Node 1 | S3-compatible Storage |
| pg-meta | Node 1 | Single-node PostgreSQL |
| pg-test | Nodes 2-4 | Three-node HA PostgreSQL |
| redis-ms | Node 1 | Redis Primary-Replica Mode |
| redis-meta | Node 2 | Redis Sentinel Mode |
| redis-test | Nodes 3-4 | Redis Native Cluster Mode |
Use Cases:
- Pigsty feature demonstration and learning
- Development testing environments
- Evaluating HA architecture
- Comparing different Redis modes
Differences from ha/trio:
- Added second PostgreSQL cluster (pg-test)
- Added three Redis cluster mode examples
- Infrastructure uses single node (instead of three nodes)
Notes:
22 - ha/safe
ha/safe uses a three-node high-availability topology to demonstrate TLS, client certificates, password checks, backup encryption, the CRIT parameter template, and related security settings. It is a configuration example to customize, not a compliance-certified template.
Overview
- Configuration:
ha/safe - Nodes: 3 INFRA, etcd, and PostgreSQL nodes; optional delayed replica
- Operating systems:
el8,el9,el10,d12,d13,u22,u24,u26 - Architecture:
x86_64; some security extensions do not have ARM64 packages - Related configurations:
ha/trio,ha/full
Generate the configuration:
-g randomizes only credentials recognized by the configuration wizard. You must still replace Silo users, the pgBackRest cipher_pass, and other template example values.
Hardening Controls
| Setting | Template Behavior | Boundary and Follow-up |
|---|---|---|
| PostgreSQL HBA | Main TCP rules use ssl; public administrator access uses cert |
Local ident and selected localhost pwd rules remain |
| PgBouncer | pgbouncer_sslmode: require |
Clients must still verify the server certificate where required |
| Patroni | REST API uses HTTPS and a constrained listen address | Basic Auth remains; rotate the password |
| Password check | passwordcheck is preloaded through pg_libs |
Affects only newly set or changed passwords |
| Account lifetime | Built-in and example application users set expire_in: 7300 |
Twenty years is not a rotation policy; shorten it to organizational requirements |
| Listen addresses | PostgreSQL is limited to ${ip},${vip},${lo} |
Firewalls and HBA are still required |
| Backup | Uses Silo with AES-256-CBC | pgBR.${pg_cluster} is a predictable example and must be replaced |
| PostgreSQL parameters | pg-meta uses crit.yml |
Strict synchronous mode can block writes without a synchronous replica |
| Logging | CRIT logs connection and disconnection events | Fine-grained SQL auditing requires explicit pgaudit configuration |
| Security extensions | Installs passwordcheck, credcheck, pgaudit, and related packages |
Installation does not preload, create, or configure an extension |
| Delayed replica | Provides a commented one-hour delayed-cluster example | Not created by default; enable it explicitly |
Preflight Checklist
- Replace every public example credential, especially
minio_users,pgbackrest_repo, application users, and API passwords. - Confirm that the three nodes occupy independent failure domains, and update IPs, VIP, and domains for the target network.
- Configure database clients with
sslmode=verify-fulland a trusted CA. - Confirm that the availability impact of strict synchronous mode meets application requirements.
- Preload and configure
pgaudit,credcheck, and other extensions as required. - Check extension package availability on ARM64.
- Test backup recovery, failover, and certificate verification.
See Security Model, Authentication, Encrypted Communication, and Data Security for the underlying mechanisms.
Configuration
Source: pigsty/conf/ha/safe.yml
23 - ha/trio
Three nodes is the minimum scale for majority-based high availability. The ha/trio template distributes INFRA, ETCD, PGSQL, and Silo across three servers. PostgreSQL, ETCD, and object storage continue serving when one server is unavailable.
Overview
- Config Name:
ha/trio - Node Count: Three nodes
- Description: Three-node standard HA architecture with a three-node, single-drive Silo cluster and one HA S3 endpoint
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
ha/dual,ha/full,ha/safe
Usage:
After configuration, modify placeholder IPs 10.10.10.11 and 10.10.10.12 to actual node IP addresses.
Content
Source: pigsty/conf/ha/trio.yml
Explanation
The ha/trio template is Pigsty’s standard HA configuration, providing true automatic failover capability.
Architecture:
- Three-node INFRA: Distributed deployment of VictoriaMetrics/Grafana/Nginx
- Three-node ETCD: DCS majority election, tolerates single-point failure
- Three-node PostgreSQL: One primary, two replicas, automatic failover
- Three-node Silo: One data path per node, using EC:1 by default (two data shards and one parity shard)
- HA S3 endpoint: Keepalived VIP
10.10.10.9with HAProxy listening on9002on all three nodes
HA Guarantees:
- Three-node ETCD tolerates one node failure, maintains majority
- PostgreSQL primary failure triggers automatic Patroni election for new primary
- L2 VIP follows primary, applications don’t need to modify connection config
- Silo retains read and write quorum while one node or one data drive is unavailable
sss.pigstyresolves to the object-storage VIP; pgBackRest andmcliusehttps://sss.pigsty:9002
Object Storage:
minio_data: /data/miniois a filesystem directory, not a raw device such as/dev/sdb.- Distributed Silo rejects data paths on the root filesystem.
/data/miniomust reside on a separately mounted/datafilesystem or be a mount point itself. - The backing storage may be a local disk, cloud volume, separate partition, or LVM logical volume. For production, prefer dedicated persistent drives of similar capacity on all three nodes.
- Use
findmnt -T /data/minioto inspect the actual mount. A result that still points to/means the path is only a directory on the root drive. - The three-node, single-drive topology provides about two-thirds raw capacity efficiency. It is compact HA; use a multi-node, multi-drive topology for greater capacity, throughput, and drive redundancy.
- A single-node object-storage pool cannot be converted in place by adding two members. Create a new three-node cluster and migrate the objects instead.
The template’s S3 API endpoint is highly available. The Portal administration UI still connects to port 9001 on the first node and is outside this API HA path.
Use Cases:
- Minimum HA deployment for production environments
- Critical business requiring automatic failover
- Foundation architecture for larger scale deployments
Extension Suggestions:
24 - ha/dual
The ha/dual template uses two-node deployment, implementing a “semi-HA” architecture with one primary and one standby. If you only have two servers, this is a pragmatic choice.
Overview
- Config Name:
ha/dual - Node Count: Two nodes
- Description: Two-node limited HA deployment, tolerates specific server failure
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
ha/trio,slim
Usage:
After configuration, modify placeholder IP 10.10.10.11 to actual standby node IP address.
Content
Source: pigsty/conf/ha/dual.yml
Explanation
The ha/dual template is Pigsty’s two-node limited HA configuration, designed for scenarios with only two servers.
Architecture:
- Node A (10.10.10.10): Admin node, runs Infra + etcd + PostgreSQL replica
- Node B (10.10.10.11): Data node, runs PostgreSQL primary only
Failure Scenario Analysis:
| Failed Node | Impact | Auto Recovery |
|---|---|---|
| Node B down | Primary switches to Node A | Auto |
| Node A etcd down | Primary continues running (no DCS) | Manual |
| Node A pgsql down | Primary continues running | Manual |
| Node A complete failure | Primary degrades to standalone | Manual |
Use Cases:
- Budget-limited environments with only two servers
- Acceptable that some failure scenarios need manual intervention
- Transitional solution before upgrading to three-node HA
Notes:
- True HA requires at least three nodes (DCS needs majority)
- Recommend upgrading to three-node architecture as soon as possible
- L2 VIP requires network environment support (same broadcast domain)
25 - ha/citus
The ha/citus template deploys a complete Citus distributed PostgreSQL cluster with 1 infra node, 1 coordinator group, and 5 worker groups (12 Citus nodes total), providing transparent horizontal scaling and data sharding.
Overview
- Config Name:
ha/citus - Node Count: 13 nodes (1 infra + 1 coordinator×2 + 5 workers×2)
- Description: Citus distributed PostgreSQL HA cluster
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64 - Related:
meta,ha/trio
Usage:
This is a 13-node template. Modify the node addresses after generation.
Content
Source: pigsty/conf/ha/citus.yml
Topology
| Cluster | Nodes | IP Addresses | VIP | Role |
|---|---|---|---|---|
| pg-meta | 1 | 10.10.10.10 | - | Infra + CMDB |
| pg-citus1 | 2 | 10.10.10.21, 22 | 10.10.10.29 | Coordinator (group 0) |
| pg-citus2 | 2 | 10.10.10.31, 32 | 10.10.10.39 | Worker (group 1) |
| pg-citus3 | 2 | 10.10.10.41, 42 | 10.10.10.49 | Worker (group 2) |
| pg-citus4 | 2 | 10.10.10.51, 52 | 10.10.10.59 | Worker (group 3) |
| pg-citus5 | 2 | 10.10.10.61, 62 | 10.10.10.69 | Worker (group 4) |
| pg-citus6 | 2 | 10.10.10.71, 72 | 10.10.10.79 | Worker (group 5) |
Architecture:
- pg-meta: Infra node running Grafana, VictoriaMetrics, etcd, plus a standalone CMDB
- pg-citus1: Coordinator (group 0), receives queries and routes to workers, 1 primary + 1 replica
- pg-citus2~6: Workers (group 1~5), store sharded data, each with 1 primary + 1 replica via Patroni
- VIP: Each group has L2 VIP managed by
vip-managerfor transparent failover
Explanation
The ha/citus template deploys production-grade Citus cluster for large-scale horizontal scaling scenarios.
Key Features:
- Horizontal Scaling: 5 worker groups for linear storage/compute scaling
- High Availability: Each group with 1 primary + 1 replica, auto-failover
- L2 VIP: Virtual IP per group, transparent failover to clients
- SSL Encryption: Inter-node communication uses SSL certificates
- Transparent Sharding: Data auto-distributed across workers
Pre-installed Extensions:
Security:
pg_dbsu_passwordenabled for Citus inter-node communication- HBA rules require SSL authentication
- Inter-node uses certificate verification:
sslmode=verify-full
Deployment
Verify after deployment:
Examples
Create Distributed Table:
Create Reference Table (replicated to all nodes):
Use Cases
- Multi-tenant SaaS: Shard by tenant_id for data isolation and parallel queries
- Real-time Analytics: Large-scale event data aggregation
- Timeseries Data: Combine with TimescaleDB for massive timeseries
- Horizontal Scaling: When single-table data exceeds single-node capacity
Notes
- PostgreSQL Version: Citus supports PG 14~18, this template defaults to PG18
- Distribution Column: Choose wisely (typically tenant_id or timestamp), critical for performance
- Cross-shard Limits: Foreign keys must include distribution column, some DDL restrictions
- Network:
pg_vip_interfacedefaults toauto; specify an interface explicitly for unusual network environments - Architecture: Citus extension does not support ARM64
26 - demo/bare
demo/bare is Pigsty’s smallest configuration example. It keeps only three core groups and three global parameters to show a working inventory skeleton.
Overview
Content
Source: pigsty/conf/demo/bare.yml
Explanation
This template relies on Pigsty defaults and defines no business users, databases, extensions, backup policy, or security hardening. Use it to learn configuration hierarchy or as a minimal customization base; explicitly add passwords, HBA rules, backup, and safeguards for a real environment.
27 - demo/el
The demo/el configuration template is optimized for Enterprise Linux family distributions (RHEL, Rocky Linux, Alma Linux, Oracle Linux).
Overview
- Config Name:
demo/el - Node Count: Single node
- Description: Enterprise Linux optimized configuration template
- OS Distro:
el8,el9,el10 - OS Arch:
x86_64,aarch64 - Related:
meta,demo/debian
Usage:
Content
Source: pigsty/conf/demo/el.yml
Explanation
The demo/el template is optimized for Enterprise Linux family distributions.
Supported Distributions:
- RHEL 8/9/10
- Rocky Linux 8/9/10
- Alma Linux 8/9/10
- Oracle Linux 8/9
Key Features:
- Uses EPEL and PGDG repositories
- Optimized for YUM/DNF package manager
- Supports EL-specific package names
Use Cases:
- Enterprise production environments (RHEL/Rocky/Alma recommended)
- Long-term support and stability requirements
- Environments using Red Hat ecosystem
28 - demo/debian
The demo/debian configuration template is optimized for Debian and Ubuntu distributions.
Overview
- Config Name:
demo/debian - Node Count: Single node
- Description: Debian/Ubuntu optimized configuration template
- OS Distro:
d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta,demo/el
Usage:
Content
Source: pigsty/conf/demo/debian.yml
Explanation
The demo/debian template is optimized for Debian and Ubuntu distributions.
Supported Distributions:
- Debian 12 (Bookworm)
- Debian 13 (Trixie)
- Ubuntu 22.04 LTS (Jammy)
- Ubuntu 24.04 LTS (Noble)
- Ubuntu 26.04 LTS (Resolute)
Key Features:
- Uses PGDG APT repositories
- Optimized for APT package manager
- Supports Debian/Ubuntu-specific package names
Use Cases:
- Cloud servers (Ubuntu widely used)
- Container environments (Debian commonly used as base image)
- Development and testing environments
29 - demo/demo
The demo/demo configuration template is used by Pigsty’s public demo site, demonstrating how to expose services publicly, configure SSL certificates, and install all available extensions.
If you want to set up your own public service on a cloud server, you can use this template as a reference.
Overview
- Config Name:
demo/demo - Node Count: Single node
- Description: Pigsty public demo site configuration
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64 - Related:
meta,rich
Usage:
Key Features
This template enhances the meta template with:
- SSL certificate and custom domain configuration (e.g.,
pigsty.cc) - Downloads and installs all available PostgreSQL 18 extensions
- Enables Docker with image acceleration
- Deploys Silo object storage
- Pre-configures multiple business databases and users
- Adds Redis primary-replica instance examples
- Adds Kafka sample cluster
Content
Source: pigsty/conf/demo/demo.yml
Explanation
The demo/demo template is Pigsty’s public demo configuration, showcasing a complete production-grade deployment example.
Key Features:
- HTTPS certificate and custom domain configuration
- All available PostgreSQL extensions installed
- Integration with Redis, Kafka, and other components
- Docker image acceleration configured
Use Cases:
- Setting up public demo sites
- Scenarios requiring complete feature demonstration
- Learning Pigsty advanced configuration
Notes:
- SSL certificate files must be prepared
- DNS resolution must be configured
- Some extensions are not available on ARM64 architecture
30 - demo/kernel
The demo/kernel configuration template demonstrates the major PostgreSQL kernels and compatible branches supported by Pigsty in a single configuration. It is intended for feature validation and kernel difference testing, not production use.
Overview
- Config Name:
demo/kernel - Node Count: 10 nodes, with one node also hosting INFRA/ETCD and
pg-citus - Description: PostgreSQL kernel matrix demo covering Citus, IvorySQL, Babelfish, PolarDB, Percona TDE, OrioleDB, OpenHalo, DocumentDB, AgensGraph, and pgEdge
- OS Distro: depends on actual package support for each kernel
- OS Arch: depends on actual package support for each kernel
- Related:
pgsql,mssql,mongo
Usage:
This is a fixed-IP demo template. Adjust node addresses for your actual environment after generation.
Content
Source: pigsty/conf/demo/kernel.yml
Explanation
This template uses single-node clusters to show the minimum viable configuration for different kernels:
pg-citus: PostgreSQL 18 + Cituspg-ivory: IvorySQL, compatible with PostgreSQL 18pg-mssql: Babelfish, compatible with PostgreSQL 17pg-polar: PolarDB for PostgreSQL, compatible with PostgreSQL 17pg-tde: Percona PostgreSQL 18 +pg_tdepg-oriole: OrioleDB, supports PostgreSQL 16, 17, and 18; the current demo config defaults to PG18pg-mysql: OpenHalo, compatible with PostgreSQL 14pg-mongo: DocumentDB backend for PostgreSQL Mongo mode, default PostgreSQL 18pg-agens: AgensGraph, compatible with PostgreSQL 17pg-edge: pgEdge, compatible with PostgreSQL 18
Notes:
- Package support varies by kernel, OS, and architecture. Confirm the target repository is available before deployment.
- This template includes permissive access rules for demo use. For production, use a dedicated kernel template and tighten HBA and password policies.
31 - demo/minio
demo/minio demonstrates a highly available S3 object-storage cluster with four nodes and four drives per node, for 16 drives total. The template retains MINIO module compatibility naming and explicitly sets minio_type: silo; the current v4.5.0 source accepts only this value, and both deployment and removal roles default to silo. Still verify it together with the exact target, cluster identity, and data paths before removal.
For more tutorials, see the MINIO module documentation.
Overview
- Config Name:
demo/minio - Node Count: Four nodes
- Description: High-availability multi-node multi-drive S3 object-storage demo (currently defaults to Silo)
- OS Distro:
el8,el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64,aarch64 - Related:
meta
Usage:
This is a four-node template. You need to modify the IP addresses of the other three nodes after generating the configuration.
Content
Source: pigsty/conf/demo/minio.yml
Explanation
demo/minio is a reference configuration for production object storage using the Multi-Node Multi-Drive (MNMD) architecture. Its volume layout, HAProxy health checks, and clients retain MinIO-compatible interfaces.
Key Features:
- Multi-Node Multi-Drive Architecture: 4 nodes × 4 drives = 16-drive erasure coding group
- L2 VIP High Availability: Virtual IP binding via Keepalived
- HAProxy Load Balancing: Unified access endpoint on port 9002
- Fine-grained Permissions: Separate users and buckets for different applications
Access:
Use Cases:
- Environments requiring S3-compatible object storage
- PostgreSQL backup storage (pgBackRest remote repository)
- Data lake for big data and AI workloads
- Production environments requiring high-availability object storage
Notes:
- Each node requires 4 independent disks mounted at
/data1-/data4 - Production environments recommend at least 4 nodes for erasure coding redundancy
- VIP requires proper network interface configuration (
vip_interface)
32 - demo/redis
demo/redis demonstrates standalone/replica, Sentinel, and native Cluster modes supported by Pigsty’s Redis module in one configuration.
Overview
- Config Name:
demo/redis - Node Count: 4
- Clusters:
redis-ms,redis-meta,redis-test - Related:
demo/demo
Content
Source: pigsty/conf/demo/redis.yml
Explanation
redis-ms: a6379primary and6380replica on one noderedis-meta: three Sentinel instances monitoring theredis-msprimaryredis-test: a native Redis Cluster across two nodes with three instances per node- Small per-instance memory limits keep the topology suitable for demonstrations
The IP addresses, passwords, and memory limits are demonstration values. Adjust them to the real topology, then install the Redis module with the redis.yml playbook.
33 - demo/kafka
demo/kafka declares two Kafka 4.x dynamic KRaft clusters across four nodes: the plaintext single-node development cluster kf-meta, and the three-node TLS/SCRAM/ACL demonstration cluster kf-test.
Overview
- Config Name:
demo/kafka - Node Count: 4
kf-meta: Single combined Broker/Controller node in plaintext modekf-test: Three combined nodes with TLS/SCRAM/ACL, topic replication factor 3, andmin.insync.replicas=2- Module Status: KAFKA BETA
deploy.yml only deploys the core path and does not run the KAFKA playbook automatically. Each kafka.yml run must select one complete Kafka cluster; the role rejects convergence against only part of a cluster.
Content
Source: pigsty/conf/demo/kafka.yml
Explanation
kf-metacreatesquickstart.eventsfor single-node development and connectivity tests.kf-testcreates thetest-appSCRAM user, prefix ACLs, and the three-replicatest.eventstopic.- Online installation maps the platform packages
kafka-stackandjava-runtime; when using only a local repository, cache both complete package groups first. - Addresses and passwords in the template are demonstration values. Replace them for your topology and security requirements before deployment.
See the KAFKA module for operations, security, and scaling constraints.
34 - demo/mysql
demo/mysql is the four-node example for the native MySQL 8.4 LTS pilot module. It is distinct from conf/mysql.yml, which provides MySQL protocol compatibility through the OpenHalo PostgreSQL kernel.
Overview
- Config Name:
demo/mysql - Node Count: 4
my-meta: Standalone MySQL 8.4 instancemy-test: Three-node, single-primary InnoDB Cluster with MySQL Router on every member- Module Status: MYSQL PILOT; not included in the stable module count
- Platform Boundary: Supported declared x86_64 RPM/DEB platforms and EL9/EL10 aarch64. Oracle APT currently has no arm64 component, so preflight rejects Debian/Ubuntu ARM.
Replace every CHANGE_ME value in the template. Real deployment also requires explicit approval. Start with read-only preflight checks:
After explicitly approving an active-inventory update, run ./configure -c demo/mysql, then run both node.yml and mysql.yml with --check and real convergence against the same complete cluster scope. The three-node cluster does not accept a partial-member scope.
Content
Source: pigsty/conf/demo/mysql.yml
Explanation
- MySQL server, client, Shell, Router, and XtraBackup are fixed to the 8.4 platform; this is not an arbitrary-version installer.
- The standalone instance uses
3306. The three-node cluster also uses Group Replication on33061, with Router RW on6446and RO on6447on each member. - A daily local full XtraBackup and
mysqld_exporterare enabled by default. The current pilot does not provide continuous binlog archiving, PITR, or automatic recovery. node.ymlinstalls the shared trust anchor at/etc/pki/ca.crt; the MySQL role only issues and installs leaf certificates.
See the native MySQL pilot documentation for complete constraints and the confirmed removal workflow.
35 - build/oss
The build/oss configuration template is the build environment configuration for Pigsty open-source edition offline packages, used to batch-build offline installation packages across multiple operating systems.
This configuration is intended for developers and contributors only.
Overview
- Config Name:
build/oss - Node Count: Seven nodes (el9, el10, d12, d13, u22, u24, u26)
- Description: Pigsty open-source edition offline package build environment
- OS Distro:
el9,el10,d12,d13,u22,u24,u26 - OS Arch:
x86_64
Usage:
This is a build template with fixed IP addresses, intended for internal use only.
Content
Source: pigsty/conf/build/oss.yml
Explanation
The build/oss template is the build configuration for Pigsty open-source edition offline packages.
Build Contents:
- PostgreSQL 18 and all categorized extension packages
- Infrastructure packages (Prometheus, Grafana, Nginx, etc.)
- Node packages (monitoring agents, tools, etc.)
- Extra modules
Supported Operating Systems:
- EL9 (Rocky/Alma/RHEL 9)
- EL10 (Rocky 10 / RHEL 10)
- Debian 12 (Bookworm)
- Debian 13 (Trixie)
- Ubuntu 22.04 (Jammy)
- Ubuntu 24.04 (Noble)
- Ubuntu 26.04 (Resolute)
Build Process:
Use Cases:
- Pigsty developers building new versions
- Contributors testing new extensions
- Enterprise users customizing offline packages
36 - build/dev
The build/dev configuration template is Pigsty’s three-node local build and development environment. It is used to validate repository build and package download workflows across EL9, Debian 12, and Ubuntu 24 nodes.
This template is intended only for developers and contributors.
Overview
- Config Name:
build/dev - Node Count: Three nodes (
el9,d12,u24) - Description: Local build and development environment, default PostgreSQL 18, builds the
infra,node,pgsqlmodules - OS Distro:
el9,d12,u24 - OS Arch:
x86_64,aarch64 - Related:
build/oss
Usage:
This is a fixed-IP development build template. Adjust host addresses for your local environment before use.
Content
Source: pigsty/conf/build/dev.yml
Explanation
build/dev is mainly used to validate the Pigsty software repository build pipeline, not for ordinary production installation.
Key Features:
- Default
pg_version: 18 - Local cache directory is
dist/${version} - Builds
infra,node,pgsqlmodules by default - Preloads PostgreSQL 18 full-category extension package groups
- Covers both RPM and DEB build paths through three distro nodes
Use Cases:
- Pigsty new version build validation
- Software repository and mirror source debugging
- Extension package download and cache testing
37 - demo/remote
demo/remote deploys no local PostgreSQL cluster. Instead, it declares multiple pg_exporters on an INFRA node to monitor remote PostgreSQL, PolarDB, or cloud RDS instances.
Overview
- Config Name:
demo/remote - Local Node Count: One INFRA node
- Example Exporter Ports:
20001-20016 - Related: PG Exporter
Content
Source: pigsty/conf/demo/remote.yml
Explanation
Each pg_exporters entry uses a unique local listen port and declares the remote instance’s pg_cluster, pg_seq, pg_host, and optional connection settings. The template demonstrates complete URLs, split credentials, database allowlists, and auto-discovery.
All hostnames and credentials are placeholders. Keep only the entries you need, use a least-privilege monitoring account, and never commit real RDS passwords.
38 - demo/saas
demo/saas is a legacy feature-rich single-node example with predefined business users, databases, and application entrypoints. It demonstrates how PostgreSQL, Silo, Redis, Docker, and the portal can be combined.
Overview
- Config Name:
demo/saas - Node Count: Single node
- Modules: INFRA, ETCD, MINIO, PGSQL, REDIS, DOCKER
- Related:
rich,supabase
Content
Source: pigsty/conf/demo/saas.yml
Explanation
The template contains placeholder database users and databases for Grafana, Bytebase, Kong, Gitea, Wiki, NocoDB, and Odoo. It uses Silo as the pgBackRest repository and includes a Redis replica example and multiple portal domains.
This compatibility/reference bundle does not install every listed application automatically. For new deployments, prefer rich plus the relevant app/* template. Remove unused users, databases, and entrypoints and replace all passwords first.
39 - demo/wool
demo/wool targets small cloud instances in China and defaults to region: china, PostgreSQL 18, and the tiny tuning profiles.
Overview
- Config Name:
demo/wool - Node Count: Single node
- Suggested Size: Approximately 2 vCPU / 2 GB for testing
- Related:
meta,slim
Content
Source: pigsty/conf/demo/wool.yml
Explanation
- Explicitly sets
pg_conf: tiny.ymlandnode_tune: tinyonpg-meta - Expects
10.10.10.10to be replaced by the cloud instance’s private IP - Disables pgBackRest by default to reduce disk usage on a small test host
- Includes several example portal domains
This template trades backup capability for lower resource use and is suitable only for temporary testing. Production deployments must enable and verify backups, tighten network rules, replace default passwords, and remove unused portal entries.