Skip to content

Commit e67c737

Browse files
jason-lynchjason-lynch
committed
docs: document preview support for systemd
Adds a page to our docs that describes the preview support for systemd using the RPM files attached to our releases. PLAT-511
1 parent 03b91fc commit e67c737

File tree

4 files changed

+202
-2
lines changed

4 files changed

+202
-2
lines changed

‎docs/installation/index.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,6 @@ In the documentation, you'll find instructions for deploying Control Plane in tw
66

77
* The [Quickstart guide](quickstart.md) deploys a three node distributed Postgres database on your local host, creating a perfect environment for experimenting with Control Plane.
88

9-
* Visit [Installing the Control Plane](installation.md) for detailed instructions for deploying a Control Plane server to your custom hosts.
9+
* Visit [Installing the Control Plane](installation.md) for detailed instructions for deploying a Control Plane server to your custom hosts.
10+
11+
* [Installing via System Packages](systemd.md) covers installing the Control Plane via system packages, without Docker. This is a **preview feature** and is not recommended for production use. Currently only supports installation through RPMs.

‎docs/installation/installation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
This guide contains instructions for deploying the Control Plane on a set of Linux hosts, such as virtual machines or bare metal servers.
44

5-
Control Plan excels at managing Postgres in a highly-available configuration. To review a list of best practices for Control Plane deployment in a high-availability environment, visit [here](../using-ha/index.md).
5+
Control Plane excels at managing Postgres in a highly-available configuration. To review a list of best practices for Control Plane deployment in a high-availability environment, visit [here](../using-ha/index.md).
66

77

88
## Initializing Docker Swarm

‎docs/installation/systemd.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# Installing the pgEdge Control Plane via System Packages
2+
3+
!!! warning "Preview Feature"
4+
5+
System package-based installation is a preview feature. Not all Control Plane
6+
features are supported, and some aspects of this
7+
installation method are subject to change. We do not recommend it for
8+
production environments yet. We'd love your feedback - please share your
9+
experience in our [GitHub issues](https://github.com/pgedge/control-plane/issues)
10+
or join our [Discord](https://discord.com/invite/pgedge/login).
11+
12+
This guide covers installing the pgEdge Control Plane on RPM-based Linux hosts
13+
(e.g. RHEL, Rocky Linux, AlmaLinux) using the RPM package attached to each
14+
[GitHub release](https://github.com/pgedge/control-plane/releases). Support for
15+
Debian-based hosts is coming in a future release.
16+
17+
Unlike the Docker Swarm installation method, the system package installation
18+
runs the Control Plane directly on the host. The Control Plane will use systemd
19+
to manage Postgres instances rather than Docker containers.
20+
21+
## Prerequisites
22+
23+
### Ports
24+
25+
By default, the Control Plane uses these ports, which must be accessible on each
26+
machine by other cluster members:
27+
28+
- Port `3000` TCP for HTTP communication
29+
- Port `2379` TCP for Etcd peer communication
30+
- Port `2380` TCP for Etcd client communication
31+
32+
You can configure alternate ports by modifying the
33+
[configuration file](#configuration) after installing the `pgedge-control-plane`
34+
RPM.
35+
36+
### Packages
37+
38+
The Control Plane depends on the pgEdge Enterprise Postgres Packages. It does
39+
not yet install Postgres or its supporting packages automatically. You must
40+
install them on each host before starting the Control Plane.
41+
42+
Run the following on each host as root:
43+
44+
```sh
45+
# Install prerequisites for the pgEdge Enterprise Postgres packages
46+
dnf install -y epel-release dnf
47+
dnf config-manager --set-enabled crb
48+
49+
# Install the pgEdge Enterprise Postgres repository
50+
dnf install -y https://dnf.pgedge.com/reporpm/pgedge-release-latest.noarch.rpm
51+
52+
# Install the required packages for your Postgres version. We currently support
53+
# versions 16, 17, and 18. Set postgres_major_version to your desired version.
54+
POSTGRES_MAJOR_VERSION='<16|17|18>'
55+
dnf install -y \
56+
pgedge-postgresql${POSTGRES_MAJOR_VERSION} \
57+
pgedge-spock50_${POSTGRES_MAJOR_VERSION} \
58+
pgedge-postgresql${POSTGRES_MAJOR_VERSION}-contrib \
59+
pgedge-pgbackrest \
60+
pgedge-python3-psycopg2
61+
62+
# Install Patroni
63+
dnf install -y python3-pip
64+
pip install 'patroni[etcd,jsonlogger]==4.1.0'
65+
```
66+
67+
## Installing the RPM
68+
69+
We publish RPMs with our releases on the
70+
[GitHub releases page](https://github.com/pgedge/control-plane/releases). RPMs
71+
are available for both `amd64` and `arm64`.
72+
73+
Install the RPM with:
74+
75+
```sh
76+
# Detect architecture
77+
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
78+
79+
# Set the version to install
80+
VERSION="v0.7.0"
81+
82+
# Download the RPM
83+
curl -LO "https://github.com/pgedge/control-plane/releases/download/${VERSION}/pgedge-control-plane_${VERSION#v}_linux_${ARCH}.rpm"
84+
85+
# Install the RPM
86+
rpm -i pgedge-control-plane_${VERSION#v}_linux_${ARCH}.rpm
87+
```
88+
89+
The RPM installs:
90+
91+
- `/usr/sbin/pgedge-control-plane` - the Control Plane binary
92+
- `/usr/lib/systemd/system/pgedge-control-plane.service` - the systemd service unit
93+
- `/etc/pgedge-control-plane/config.json` - the default configuration file
94+
95+
## Configuration
96+
97+
The default configuration file is located at
98+
`/etc/pgedge-control-plane/config.json`:
99+
100+
```json
101+
{
102+
"orchestrator": "systemd",
103+
"data_dir": "/var/lib/pgedge-control-plane"
104+
}
105+
```
106+
107+
The `orchestrator` field must be set to `"systemd"` for this installation
108+
method. The `data_dir` is where the Control Plane stores its state, including
109+
the embedded Etcd data.
110+
111+
The host ID defaults to the machine's short hostname. To set an explicit host
112+
ID, add a `host_id` field to the config file:
113+
114+
```json
115+
{
116+
"orchestrator": "systemd",
117+
"data_dir": "/var/lib/pgedge-control-plane",
118+
"host_id": "my-host-1"
119+
}
120+
```
121+
122+
You can find the full list of configuration settings in the
123+
[Configuration reference](./configuration.md).
124+
125+
## Starting the Control Plane
126+
127+
Start and enable the Control Plane service:
128+
129+
```sh
130+
systemctl enable --now pgedge-control-plane.service
131+
```
132+
133+
To check the service status:
134+
135+
```sh
136+
systemctl status pgedge-control-plane.service
137+
```
138+
139+
To tail the logs:
140+
141+
```sh
142+
journalctl -u pgedge-control-plane.service --follow
143+
```
144+
145+
## Initializing the Control Plane
146+
147+
Once the service is running on all hosts, initialize and join them the same way
148+
as a Docker Swarm installation.
149+
150+
Initialize the cluster on the first host:
151+
152+
```sh
153+
curl http://localhost:3000/v1/cluster/init
154+
```
155+
156+
The response contains a join token and server URL:
157+
158+
```json
159+
{
160+
"token": "PGEDGE-0c470f2eac35bb25135654a8dd9c812fc4aca4be8c8e34483c0e279ab79a7d30-907336deda459ebc79079babf08036fc",
161+
"server_urls": ["http://198.19.249.2:3000"]
162+
}
163+
```
164+
165+
Join each additional host to the cluster by submitting a `POST` request to that
166+
host's `/v1/cluster/join` endpoint with the token and server URL from the
167+
previous step:
168+
169+
```sh
170+
curl -i -X POST http://<host_ip>:3000/v1/cluster/join \
171+
-H 'Content-Type: application/json' \
172+
--data '{
173+
"token": "PGEDGE-0c470f2eac35bb25135654a8dd9c812fc4aca4be8c8e34483c0e279ab79a7d30-907336deda459ebc79079babf08036fc",
174+
"server_urls": ["http://198.19.249.2:3000"]
175+
}'
176+
```
177+
178+
Repeat for each host. Once all hosts have joined, you can interact with the API
179+
from any host in the cluster.
180+
181+
## Updating the Control Plane
182+
183+
To update to a newer version, download the new RPM from the
184+
[GitHub releases page](https://github.com/pgedge/control-plane/releases) and
185+
run:
186+
187+
```sh
188+
systemctl stop pgedge-control-plane.service
189+
rpm -U pgedge-control-plane-<new-version>.<arch>.rpm
190+
systemctl start pgedge-control-plane.service
191+
```
192+
193+
!!! note
194+
195+
The RPM upgrade (`rpm -U`) preserves your existing configuration file at
196+
`/etc/pgedge-control-plane/config.json` because it is marked as a
197+
non-replaceable config file.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ nav:
6363
- Configuration Options: installation/configuration.md
6464
- Upgrading a Control Plane Installation: installation/upgrading.md
6565
- Configuring mTLS: installation/mtls.md
66+
- Installing the pgEdge Control Plane via System Packages: installation/systemd.md
6667
- Managing a High-Availability Environment:
6768
- Best Practices for Deploying a High-Availability Cluster: using-ha/index.md
6869
- Connecting to a High-Availability Cluster: using-ha/ha-connections.md

0 commit comments

Comments
 (0)