# Installation > How to install Pigsty? --- > Install Pigsty with 4 steps: [Prepare](#prepare), [Download](#download), [Configure](#configure) and [Install](#install). > > Also check [offline installation](/docs/setup/offline) if you don't have the Internet access. ---------------- ## Short Version [Prepare](#prepare) a fresh Linux x86_64 node that runs [compatible](/docs/reference/compatibility) OS, then run as a **sudo-able** user: ```bash curl -L https://get.pigsty.cc/install | bash -s v2.7.0 ``` It will [download](#download) Pigsty source to your home, then perform [configure](#configure) and [install](#install) to finish the installation. ```bash cd ~/pigsty # get pigsty source and entering dir ./bootstrap # download bootstrap pkgs & ansible [optional] ./configure # pre-check and config templating [optional] ./install.yml # install pigsty according to pigsty.yml ``` A pigsty singleton node will be ready with Web [Interface](#interface) on port `80/443` and Postgres [service](/docs/concept/svc/) on port `5432`. You can add [more](#more) nodes into Pigsty and deploy [modules](/docs/about/module/) on them. **Example: Online Singleton Installation on Ubuntu 22.04:** [![asciicast](https://asciinema.org/a/659640.svg)](https://asciinema.org/a/659640)
Example: Install with Offline Package (EL8) [![asciicast](https://asciinema.org/a/659637.svg)](https://asciinema.org/a/659637)
----------------------- ## Prepare > Check [Preparation](/docs/setup/prepare) for a complete guide of resource preparation. Pigsty support the `Linux` kernel and `x86_64/amd64` arch. It can run on any nodes: bare metal, virtual machines, or VM-like containers, but a **static** IPv4 address is required. The minimum spec is `1C1G`. It is recommended to use bare metals or VMs with at least `2C4G`. There's no upper limit, and node param will be auto-tuned. We recommend using fresh **RockyLinux 8.9** or **Ubuntu 22.04.3** as underlying operating systems. For a complete list of supported operating systems, please refer to [**Compatibility**](/docs/reference/compatibility). Public key `ssh` access to localhost and NOPASSWD `sudo` privilege is required to perform the installation, Try not using the `root` user. If you wish to manage more nodes, these nodes needs to be `ssh` / `sudo` accessible via your current admin node & admin user. Pigsty relies on Ansible to execute playbooks. you have to install `ansible` and `jmespath` packages fist to run the [**install**](#install) procedure. This can be done with the following command, or through the [**`bootstrap`**](/docs/setup/offline#bootstrap) procedure, especially when you do not have internet access.. **Install Ansible** **EL 8 \/ 9** sudo dnf install -y ansible python3.11-jmespath python3-cryptography **EL 7** sudo yum install -y ansible # EL7 does not need to install jmespath explicitly **Debian \/ Ubuntu** sudo apt install -y ansible python3-jmespath **MacOS** brew install ansible **Do NOT use the root user** While it is possible to install Pigsty as the `root` user, It would be much safer using a dedicate admin user (`dba`, `admin`, ...). due to [security](/docs/setup/security/) consideration which has to be different from `root` and dbsu (`postgres`). Pigsty will create an optional admin user `dba` according to the config by default. ----------------------- ## Download You can get & extract pigsty source via the following command: ```bash curl -fsSL https://get.pigsty.cc/install | bash -s v2.7.0 ```
Download Example Output ```bash $ bash -c "$(curl -fsSL https://get.pigsty.cc/install)" -- v2.7.0 [v2.7.0] =========================================== $ curl -fsSL https://pigsty.cc/install | bash -s v2.7.0 [Site] https://pigsty.io [Demo] https://demo.pigsty.cc [Repo] https://github.com/Vonng/pigsty [Docs] https://pigsty.io/docs/setup/install [Download] =========================================== [ OK ] version = v2.7.0 (from default) curl -fSL https://get.pigsty.cc/v2.7.0/pigsty-v2.7.0.tgz -o /tmp/pigsty-v2.7.0.tgz ########################################################################### 100.0% [ OK ] md5sums = some_random_md5_hash_value_here_ /tmp/pigsty-v2.7.0.tgz [Install] =========================================== [ OK ] install = /home/vagrant/pigsty, from /tmp/pigsty-v2.7.0.tgz [Resource] =========================================== [HINT] rocky 8 have [OPTIONAL] offline package available: https://pigsty.io/docs/setup/offline curl -fSL https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-pkg-v2.7.0.el8.x86_64.tgz -o /tmp/pkg.tgz curl -fSL https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.el8.x86_64.tgz -o /tmp/pkg.tgz # or use alternative CDN [TodoList] =========================================== cd /home/vagrant/pigsty ./bootstrap # [OPTIONAL] install ansible & use offline package ./configure # [OPTIONAL] preflight-check and config generation ./install.yml # install pigsty modules according to your config. [Complete] =========================================== ``` **Install a specific version** HINT: To install a specific version, passing the version string as the first parameter: ```bash bash -c "$(curl -fsSL https://get.pigsty.cc/i)" -- v2.7.0 # install the specific version: v2.7.0 curl -fsSL https://get.pigsty.cc/i | bash -s v2.7.0 # another approach to passing parameter ```

If you don't have the Internet access, check [**offline installation**](/docs/setup/offline) for details. You can download the source tarball with the following links and upload them with scp, ftp, etc... - GitHub： https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-v2.7.0.tgz - Mirror： https://get.pigsty.cc/v2.7.0/pigsty-v2.7.0.tgz ```bash curl https://get.pigsty.cc/v2.7.0/pigsty-v2.7.0.tgz -o pigsty.tgz tar -xvf pigsty.tgz -C ~ ; cd ~/pigsty ; # download manually and extract to home dir ``` You can also use `git` to download the Pigsty source. Please make sure to **check out a specific version** before using. ```bash git clone https://github.com/Vonng/pigsty; cd pigsty; git checkout v2.7.0; ``` **Checkout a specific Version** The `master` branch may in an unstable development status. Always checkout a version when using `git`, check [Release Notes](/docs/releasenote) for available versions. ----------------------- ## Configure [`configure`](/docs/setup/config) will create a [`pigsty.yml`](https://github.com/Vonng/pigsty/blob/v2.7.0/pigsty.yml) [config](/docs/setup/config/) file according to your env. This procedure is **OPTIONAL** if you know how to [configure](/docs/setup/config) pigsty manually. ```bash ./configure # interactive-wizard, ask for IP address ./configure [-i|--ip ] [-m|--mode ] # give primary IP & config mode [-r|--region ] # choose upstream repo region [-n|--non-interactive] # skip interactive wizard [-x|--proxy] # write proxy env to config ```
Configure Example Output ```bash $ ./configure configure pigsty v2.7.0 begin [ OK ] region = china [ OK ] kernel = Linux [ OK ] machine = x86_64 [ OK ] package = rpm,dnf [ OK ] vendor = rocky (Rocky Linux) [ OK ] version = 8 (8.9) [ OK ] sudo = vagrant ok [ OK ] ssh = vagrant@127.0.0.1 ok [WARN] Multiple IP address candidates found: (1) 192.168.121.165 inet 192.168.121.165/24 brd 192.168.121.255 scope global dynamic noprefixroute eth0 (2) 10.10.10.8 inet 10.10.10.8/24 brd 10.10.10.255 scope global noprefixroute eth1 [ IN ] INPUT primary_ip address (of current meta node, e.g 10.10.10.10): => 10.10.10.8 # input the primary IP address itself, if there's multiple candidates [ OK ] primary_ip = 10.10.10.8 (from input) [ OK ] admin = vagrant@10.10.10.8 ok [ OK ] config = el @ 10.10.10.8 [tiny -> oltp] [ OK ] configure pigsty done proceed with ./install.yml ```

* `-m|--mode`: Generate config from [templates](https://github.com/Vonng/pigsty/tree/v2.7.0/files/pigsty) according to `mode`: (`auto|demo|sec|citus|el|el7|ubuntu|prod...`) * `-i|--ip`: Replace IP address placeholder `10.10.10.10` with your primary ipv4 address of current node. * `-r|--region`: Set upstream repo mirror according to `region` (`default|china|europe`) * `-n|--non-interactive`: skip interactive wizard and using default/arg values * `-x|--proxy`: write current proxy env to the config [`proxy_env`](/docs/reference/param#proxy_env) (`http_proxy`/`HTTP_PROXY`， `HTTPS_PROXY`， `ALL_PROXY`， `NO_PROXY`) When `-n|--non-interactive` is specified, you have to specify a primary IP address with `-i|--ip ` in case of multiple IP address, since there's no default value for primary IP address in this case. If your machine's network interface have multiple IP addresses, you'll need to explicitly specify a **primary** IP address for the current node using `-i|--ip `, or provide it during interactive inquiry. The address should be a static IP address, and you should avoid using any public IP addresses. You can check and modify the generated config file `~/pigsty/pigsty.yml` before installation. **Change the default passwords!** PLEASE CHANGE THE DEFAULT PASSWORDs in the config file before installation, check [secure password](/docs/setup/security/#passwords) for details. ----------------------- ## Install Run the [`install.yml`](https://github.com/Vonng/pigsty/blob/v2.7.0/install.yml) playbook to perform a full installation on current node ```bash ./install.yml # install everything in one-pass ```
Installation Output Example ```bash [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 ```
It's a standard ansible [**playbook**](/docs/setup/playbook), you can have fine-grained control with ansible options: * `-l`: limit execution targets * `-t`: limit execution tasks * `-e`: passing extra args * `-i`: use another config * ... **Don't Ever run this Again!** It's very DANGEROUS to re-run [**`install.yml`**](https://github.com/Vonng/pigsty/blob/v2.7.0/install.yml) on existing deployment!** You can use `chmod a-x install.yml` to avoid accidental execution. ----------------------- ## Interface Once installed, you'll have four [core modules](/docs/about/module#core-modules) [**`PGSQL`**](/docs/pgsql), [**`INFRA`**](/docs/infra), [**`NODE`**](/docs/node), and [**`ETCD`**](/docs/etcd) the current node. The [**PGSQL**](/docs/pgsql) provides a PostgreSQL singleton which can be [accessed](/docs/concept/svc#personal-user) via: **Default Users** **dbuser\_dba** psql postgres://dbuser_dba:DBUser.DBA@10.10.10.10/meta # DBA / superuser (via IP) **dbuser\_meta** psql postgres://dbuser_meta:DBUser.Meta@10.10.10.10/meta # business admin, read / write / ddl **dbuser\_view** psql postgres://dbuser_view:DBUser.View@pg-meta/meta # read-only user The [**INFRA**](/docs/infra) module gives you an entire modern observability stack, exposed by Nginx on (`80` / `443`): There are several services are exposed by Nginx (configured by [`infra_portal`](/docs/reference/param/#infra_portal)): | Component | Port | Domain | Comment | Public Demo | |:------------:|:----------:|:----------:|--------------------------|--------------------------------------------| | **Nginx** | **80/443** | `h.pigsty` | Web Service Portal, Repo | [`home.pigsty.cc`](http://home.pigsty.cc) | | AlertManager | 9093 | `a.pigsty` | Alter Aggregator | [`a.pigsty.cc`](http://a.pigsty.cc) | | **Grafana** | **3000** | `g.pigsty` | Grafana Dashboard Home | [`demo.pigsty.cc`](https://demo.pigsty.cc) | | Prometheus | 9090 | `p.pigsty` | Prometheus Web UI | [`p.pigsty.cc`](http://p.pigsty.cc) | > Grafana Dashboards (g.pigsty, port 3000) credentials, user: `admin` / pass: `pigsty` [![pigsty-home.jpg](/img/pigsty/home.jpg)](https://demo.pigsty.cc) You can access these web UI directly via IP + port. While the common best practice would be access them through Nginx and distinguish via domain names. You'll need configure DNS records, or use the local static records (`/etc/hosts`) for that.
How to access Pigsty Web UI by domain name?
There are several options: 1. Resolve internet domain names through a DNS service provider, suitable for systems accessible from the public internet. 2. Configure internal network DNS server resolution records for internal domain name resolution. 3. Modify the local machine's `/etc/hosts` file to add static resolution records. (For Windows, it's located at:) We recommend the third method for common users. On the machine (which runs the browser), add the following record into `/etc/hosts` (sudo required) or `C:\Windows\System32\drivers\etc\hosts` in Windows: ``` h.pigsty a.pigsty p.pigsty g.pigsty ``` You have to use the **external** IP address of the node here.

How to configure server side domain names?
The server-side domain name is configured with Nginx. If you want to replace the default domain name, simply enter the domain you wish to use in the parameter [`infra_portal`](/docs/reference/param#infra_portal). When you access the Grafana monitoring homepage via `http://g.pigsty`, it is actually accessed through the Nginx proxy to Grafana's WebUI: ``` http://g.pigsty ️-> http://10.10.10.10:80 (nginx) -> http://10.10.10.10:3000 (grafana) ``` If [`nginx_sslmode`](/docs/reference/param/#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.

How to use HTTPS in Pigsty WebUI?
Pigsty will generate self-signed certs for Nginx, if you wish to access via HTTPS without "Warning", here are some options: - Apply & add real certs from trusted CA: such as Let's Encrypt - Trust your generated CA crt as root ca in your OS and browser - Type `thisisunsafe` in Chrome will supress the warning
----------------------- ## More You can deploy & monitor more clusters with pigsty: add more nodes to `pigsty.yml` and run corresponding playbooks: ```bash 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 ``` Remember that most modules require the [`NODE`] module installed first. Check [modules](/docs/about/module/) for detail [**`PGSQL`**](/docs/pgsql), [**`INFRA`**](/docs/infra), [**`NODE`**](/docs/node), [**`ETCD`**](/docs/etcd), [**`MINIO`**](/docs/minio), [**`REDIS`**](/docs/redis), [**`MONGO`**](/docs/mongo), [**`DOCKER`**](/docs/node), ……

----------------