Get Started

How to get Pigsty?

It takes four steps to install Pigsty: Download, Bootstrap, Configure and Install.

Short Version

Prepare a new node with Linux x86_64 EL compatible OS, then run as a sudo-able user:

1. bash -c "$(curl -fsSL http://download.pigsty.cc/get)"
2. cd ~/pigsty   # get pigsty source and entering dir
3. ./bootstrap   # download bootstrap pkgs & ansible [optional]
4. ./configure   # pre-check and config templating   [optional]
5. ./install.yml # install pigsty according to pigsty.yml

Then you will have a pigsty singleton node ready, with Web Services on port 80 and Postgres on port 5432.

Download via Git

You can also download pigsty source with git, don’t forget to checkout a specific version.

1. git clone https://github.com/Vonng/pigsty;
2. cd pigsty; git checkout v2.0.2

Requirement

OS

  • Linux RHEL or other compatible distributions
  • Vendor: RHEL, CentOS, Rocky, AlmaLinux, …
  • Version: el7, el8, el9, and compatible releases
  • Please use fresh new nodes for installation to avoid meaningless issues

Node

  • x86_64 architecture (aarch64 is not officially supported)
  • 1 core & 1 GB RAM (at least 2C/4G is recommended for meta node)
  • nopass ssh access to root or any sudo-able user

Ansible

  • Ansible is required and will be installed during bootstrap procedure
  • You can also manually install it with yum, and epel-release enabled

HINT: Recommended Releases are CentOS 7.9 / RockyLinux 8.6 / RockyLinux 9.0, which are tested and verified.

Download

You can get & extract pigsty source via the following command:

1. curl -fsSL http://download.pigsty.cc/get  | bash

HINT: Get the latest beta release with getb instead of get.

Download Pigsty Source with Specific Version

If you want to download a specific version, use the following URLs:

1. VERSION=v2.0.2
2. https://github.com/Vonng/pigsty/releases/download/${VERSION}/pigsty-${VERSION}.tgz

For example, Pigsty v2.0.2 source can be acquired with:

1. curl -L https://github.com/Vonng/pigsty/releases/download/v2.0.2/pigsty-v2.0.2.tgz -o ~/pigsty.tgz
2. curl -L http://download.pigsty.cc/v2.0.2/pigsty-v2.0.2.tgz -o ~/pigsty.tgz   # China CDN Mirror

Offline Packages

Pigsty downloads rpm packages from the upstream yum repo during installation. Which can be accelerated dramatically by using a local mirror: offline packages. It’s also extremely useful when you have no Internet available.

The bootstrap script will ask for download the corresponding offline package (--yes|--no) and setup everything up for you. You can also download it manually and put it under /tmp/pkg.tgz for later use.

Download offline packages manually

1. VERSION=v2.0.2
2. OS_VERSION=$(rpm -q --qf "%{VERSION}" $(rpm -q --whatprovides redhat-release) | grep -o '^[^.]\+')
3. ARCH=$(uname -m)
4. FILENAME=pigsty-pkg-${VERSION}.el${OS_VERSION}.${ARCH}.tgz
5. PKG_URL="https://github.com/Vonng/pigsty/releases/download/${VERSION}/${FILENAME}"
6. echo ${PKG_URL} && curl -L ${PKG_URL} -o /tmp/pkg.tgz

For example, Pigsty v2.0.2 on EL7.x86_64 will have the following packages:

1. curl -L https://github.com/Vonng/pigsty/releases/download/v2.0.2/pigsty-pkg-v2.0.2.el7.x86_64.tgz  -o /tmp/pkg.tgz
2. curl -L http://download.pigsty.cc/v2.0.2/pigsty-pkg-v2.0.2.el7.x86_64.tgz -o /tmp/pkg.tgz  # China CDN Mirror

Not all combinations of OS and architecture are supported yet. Please check the official release page.

Bootstrap

bootstrap script will make sure one thing: ansible is ready for using.

It will also download / extract / setup the offline packages if you choose to do so.

1. ./boostrap [-p <path>=/tmp/pkg.tgz]   # offline pkg path (/tmp/pkg.tgz by default)
2. [-y|--yes] [-n|--no]       # download packages or not? (ask by default)

HINT: bootstrap is OPTIONAL if you already have ansible and plan to download rpm packages from upstream directly.

bootstrap procedure detail

  1. Check preconditions

  2. Check local repo exists ?

  3. Y -> create /etc/yum.repos.d/pigsty-local.repo to enable it

  4. N -> Download offline package from the Internet?

    • Y -> Download from Github / CDN and extract & enable it
    • N -> Add basic os upstream repo file manually ?
    • Y -> add according to region / releasever
    • N -> leave it to user’s default configuration

  5. Now we have an available repo for installing ansible

  6. Precedence: local pkg.tgz > downloaded pkg.tgz > upstream > user provide

  7. install boot utils from the available repo

  8. el7,8,9: nginx wget sshpass createrepo_c yum-utils

  9. el8,9 extra: dnf-utils modulemd-tools python3-jmespath
  10. Check ansible availability.

bootstrap from local packages output

If /tmp/pkg.tgz already exists, bootstrap will use it directly:

1. bootstrap pigsty v2.0.2 begin
2. [ OK ] region = china
3. [ OK ] kernel = Linux
4. [ OK ] machine = x86_64
5. [ OK ] release = 7.9.2009
6. [ OK ] sudo = vagrant ok
7. [ OK ] cache = /tmp/pkg.tgz exists
8. [ OK ] repo = extract from /tmp/pkg.tgz
9. [ OK ] repo file = use /etc/yum.repos.d/pigsty-local.repo
10. [ OK ] repo cache = created
11. [ OK ] install el7 utils
12. ....(yum install ansible output)
13. [ OK ] ansible = ansible 2.9.27
14. [ OK ] boostrap pigsty complete
15. proceed with ./configure
16. ``` bootstrap download from internet output

18. Download `pkg.tgz` from Github and extract it:

bootstrap pigsty v2.0.2 begin [ OK ] region = china [ OK ] kernel = Linux [ OK ] machine = x86_64 [ OK ] release = 7.9.2009 [ OK ] sudo = vagrant ok [ IN ] Cache /tmp/pkg.tgz not exists, download? (y/n): => y [ OK ] download from Github http://download.pigsty.cc/v2.0.2/pigsty-pkg-v2.0.2.el7.x86_64.tgz to /tmp/pkg.tgz % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 913M 100 913M 0 0 661k 0 0:23:33 0:23:33 —:—:— 834k [ OK ] repo = extract from /tmp/pkg.tgz [ OK ] repo file = use /etc/yum.repos.d/pigsty-local.repo [ OK ] repo cache = created [ OK ] install el7 utils

…… (yum install createrepo_c sshpass unzip output)

Package Arch Version Repository Size

Installing: createrepo_c x86_64 0.10.0-20.el7 pigsty-local 65 k sshpass x86_64 1.06-2.el7 pigsty-local 21 k unzip x86_64 6.0-24.el7_9 pigsty-local 172 k Installing for dependencies: createrepo_c-libs x86_64 0.10.0-20.el7 pigsty-local 89 k

Transaction Summary

…… (yum install ansible output)

Package Arch Version Repository Size

Installing: ansible noarch 2.9.27-1.el7 pigsty-local 17 M Installing for dependencies: PyYAML x86_64 3.10-11.el7 pigsty-local 153 k libyaml x86_64 0.1.4-11.el7_0 pigsty-local 55 k python-babel noarch 0.9.6-8.el7 pigsty-local 1.4 M python-backports x86_64 1.0-8.el7 pigsty-local 5.8 k python-backports-ssl_match_hostname noarch 3.5.0.1-1.el7 pigsty-local 13 k python-cffi x86_64 1.6.0-5.el7 pigsty-local 218 k python-enum34 noarch 1.0.4-1.el7 pigsty-local 52 k python-idna noarch 2.4-1.el7 pigsty-local 94 k python-ipaddress noarch 1.0.16-2.el7 pigsty-local 34 k python-jinja2 noarch 2.7.2-4.el7 pigsty-local 519 k python-markupsafe x86_64 0.11-10.el7 pigsty-local 25 k python-paramiko noarch 2.1.1-9.el7 pigsty-local 269 k python-ply noarch 3.4-11.el7 pigsty-local 123 k python-pycparser noarch 2.14-1.el7 pigsty-local 104 k python-setuptools noarch 0.9.8-7.el7 pigsty-local 397 k python-six noarch 1.9.0-2.el7 pigsty-local 29 k python2-cryptography x86_64 1.7.2-2.el7 pigsty-local 502 k python2-httplib2 noarch 0.18.1-3.el7 pigsty-local 125 k python2-jmespath noarch 0.9.4-2.el7 pigsty-local 41 k python2-pyasn1 noarch 0.1.9-7.el7 pigsty-local 100 k

Transaction Summary

… Complete! [ OK ] ansible = ansible 2.9.27 [ OK ] boostrap pigsty complete proceed with ./configure

2. ---

4. ## Configure

6. [configure]($ffb11dc120032ea7.md) will create a [pigsty.yml](https://github.com/Vonng/pigsty/blob/master/pigsty.yml) config file according to your environment.

./configure [-n|—non-interactive] [-i|—ip ] [-m|—mode ] [-r|—region ]

2. -   `-m|--mode`: Generate config from [templates](https://github.com/Vonng/pigsty/tree/master/files/pigsty) according to `mode`: (`auto|demo|sec|citus|el8|el9|...`)
3. -   `-i|--ip`: Replace IP address placeholder `10.10.10.10` with your primary ipv4 address of current node.
4. -   `-r|--region`: Set upstream repo mirror according to `region` (`default|china|europe`)
5. -   `-n|--non-interactive`: skip interactive wizard and using default/arg values

7. When `-n|--non-interactive` is specified, you have to specify a primary IP address with `-i|--ip <ipaddr>` in case of multiple IP address, since there’s no default value for primary IP address in this case.

9. ?&gt; HINT: `configure` is **OPTIONAL** if you know how to [configure]($ffb11dc120032ea7.md) pigsty manually.

11. configure example output

[vagrant@meta pigsty]$ ./configure configure pigsty v2.0.2 begin [ OK ] region = china [ OK ] kernel = Linux [ OK ] machine = x86_64 [ OK ] sudo = vagrant ok [ OK ] ssh = vagrant@127.0.0.1 ok [WARN] Multiple IP address candidates found: (1) 10.0.2.15 inet 10.0.2.15/24 brd 10.0.2.255 scope global noprefixroute dynamic eth0 (2) 10.10.10.10 inet 10.10.10.10/24 brd 10.10.10.255 scope global noprefixroute eth1 [ OK ] primary_ip = 10.10.10.10 (from demo) [ OK ] admin = vagrant@10.10.10.10 ok [ OK ] mode = demo (vagrant demo) [ OK ] config = demo @ 10.10.10.10 [ OK ] ansible = ansible 2.9.27 [ OK ] configure pigsty done proceed with ./install.yml

2. ---

4. ## Install

6. You can run [install.yml](https://github.com/Vonng/pigsty/blob/master/pigsty.yml) to perform a full installation on current node

./install.yml # install everything in one-pass

2. It’s a standard ansible playbook, you can have fine-grained control with ansible options:

4. -   `-l`: limit execution targets
5. -   `-t`: limit execution tasks
6. -   `-e`: passing extra args
7. -   …

9. Check playbooks for more available functionalities.

11. > **WARNING: It’s very DANGEROUS to run [install.yml](https://github.com/Vonng/pigsty/blob/master/install.yml) on existing deployment!**

13. Installation Output Example

[vagrant@meta pigsty]$ ./install.yml

PLAY [IDENTITY] ********************

TASK [node_id : get node fact] ***************** changed: [10.10.10.12] changed: [10.10.10.11] changed: [10.10.10.13] changed: [10.10.10.10] … … PLAY RECAP ************************** 10.10.10.10 : ok=288 changed=215 unreachable=0 failed=0 skipped=64 rescued=0 ignored=0 10.10.10.11 : ok=263 changed=194 unreachable=0 failed=0 skipped=88 rescued=0 ignored=1 10.10.10.12 : ok=263 changed=194 unreachable=0 failed=0 skipped=88 rescued=0 ignored=1 10.10.10.13 : ok=153 changed=121 unreachable=0 failed=0 skipped=53 rescued=0 ignored=1 localhost : ok=3 changed=0 unreachable=0 failed=0 skipped=4 rescued=0 ignored=0

2. ---

4. ## Interface

6. Once installed, you’ll have 4 module [INFRA]($8515dc6e819753e1.md), [NODE]($135a246ab81b97d6.md), [ETCD]($b1d456437fde9bf4.md) , [PGSQL]($57d9b661508bbbed.md) installed on the current node.

8. -   [INFRA]($8515dc6e819753e1.md): Monitoring infrastructure can be accessed via `http://<ip>:80`
9. -   [PGSQL]($57d9b661508bbbed.md): PostgreSQL cluster can be accessed via default PGURL: `postgres://dbuser_meta:DBUser.Meta@<ip>:5432/meta`

11. There are several services are exposed by Nginx (configured by [infra\_portal]($0f98c5a580729801.md#infra_portal)):

13. &lt;table>&lt;thead>&lt;tr>&lt;th>Component&lt;/th>&lt;th>Port&lt;/th>&lt;th>Domain&lt;/th>&lt;th>Comment&lt;/th>&lt;th>Public Demo&lt;/th>&lt;/tr>&lt;/thead>&lt;tbody>&lt;tr>&lt;td>Nginx&lt;/td>&lt;td>80&lt;/td>&lt;td>&lt;code>h.pigsty&lt;/code>&lt;/td>&lt;td>Web Service Portal, Repo&lt;/td>&lt;td>&lt;a href="http://home.pigsty.cc">home.pigsty.cc&lt;/a>&lt;/td>&lt;/tr>&lt;tr>&lt;td>AlertManager&lt;/td>&lt;td>9093&lt;/td>&lt;td>&lt;code>a.pigsty&lt;/code>&lt;/td>&lt;td>Alter Aggregator&lt;/td>&lt;td>&lt;a href="http://a.pigsty.cc">a.pigsty.cc&lt;/a>&lt;/td>&lt;/tr>&lt;tr>&lt;td>Grafana&lt;/td>&lt;td>3000&lt;/td>&lt;td>&lt;code>g.pigsty&lt;/code>&lt;/td>&lt;td>Grafana Dashboard Home&lt;/td>&lt;td>&lt;a href="http://demo.pigsty.cc">demo.pigsty.cc&lt;/a>&lt;/td>&lt;/tr>&lt;tr>&lt;td>Prometheus&lt;/td>&lt;td>9090&lt;/td>&lt;td>&lt;code>p.pigsty&lt;/code>&lt;/td>&lt;td>Prometheus Web UI&lt;/td>&lt;td>&lt;a href="http://p.pigsty.cc">p.pigsty.cc&lt;/a>&lt;/td>&lt;/tr>&lt;/tbody>&lt;/table>

15. You can configure public domain names for these infra services or just use local static DNS records & resolver. e.g., write records to `/etc/hosts` and access via DNS.

17. If [nginx\_sslmode]($0f98c5a580729801.md#nginx_sslmode) is set to `enabled` or `enforced`, you can trust self-signed ca: `files/pki/ca/ca.crt` to use `https` in your browser.

http://g.pigsty ️-> http://10.10.10.10:80 (nginx) -> http://10.10.10.10:3000 (grafana)

2. > Default credential for grafana: username: `admin`, password: `pigsty`

4. ---

6. ## More

8. You can deploy & monitor more clusters with pigsty: add more nodes to `pigsty.yml` and run corresponding playbooks:

bin/node-add pg-test # init 3 nodes of cluster pg-test bin/pgsql-add pg-test # init HA PGSQL Cluster pg-test bin/redis-add redis-ms # init redis cluster redis-ms ```

Check PGSQL, NODE, and REDIS for detail.

Last modified 2023-04-07: bump en docs to v2.0.2 (5a16652)