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 ?

    • Y -> create /etc/yum.repos.d/pigsty-local.repo to enable it
    • 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
  • Now we have an available repo for installing ansible
    • Precedence: local pkg.tgz > downloaded pkg.tgz > upstream > user provide

  1. install boot utils from the available repo

    • el7,8,9: nginx wget sshpass createrepo_c yum-utils
    • el8,9 extra: dnf-utils modulemd-tools python3-jmespath
  2. 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. <table><thead><tr><th>Component</th><th>Port</th><th>Domain</th><th>Comment</th><th>Public Demo</th></tr></thead><tbody><tr><td>Nginx</td><td>80</td><td><code>h.pigsty</code></td><td>Web Service Portal, Repo</td><td><a href="http://home.pigsty.cc">home.pigsty.cc</a></td></tr><tr><td>AlertManager</td><td>9093</td><td><code>a.pigsty</code></td><td>Alter Aggregator</td><td><a href="http://a.pigsty.cc">a.pigsty.cc</a></td></tr><tr><td>Grafana</td><td>3000</td><td><code>g.pigsty</code></td><td>Grafana Dashboard Home</td><td><a href="http://demo.pigsty.cc">demo.pigsty.cc</a></td></tr><tr><td>Prometheus</td><td>9090</td><td><code>p.pigsty</code></td><td>Prometheus Web UI</td><td><a href="http://p.pigsty.cc">p.pigsty.cc</a></td></tr></tbody></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)