Skip to content

Commit 7f41594

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 e8b57e4 commit 7f41594

4 files changed

Lines changed: 174 additions & 2 deletions

File tree

‎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: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
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+
The Control Plane depends on the pgEdge Enterprise Postgres Packages. It does
24+
not yet install Postgres or its supporting packages automatically. You must
25+
install them on each host before starting the Control Plane.
26+
27+
Run the following on each host as root:
28+
29+
```sh
30+
# Install prerequisites for the pgEdge Enterprise Postgres packages
31+
dnf install -y epel-release dnf
32+
dnf config-manager --set-enabled crb
33+
34+
# Install the pgEdge Enterprise Postgres repository
35+
dnf install -y https://dnf.pgedge.com/reporpm/pgedge-release-latest.noarch.rpm
36+
37+
# Install the required packages for your Postgres version. We currently support
38+
# versions 16, 17, and 18. Set postgres_major_version to your desired version.
39+
POSTGRES_MAJOR_VERSION='<16|17|18>'
40+
dnf install -y \
41+
pgedge-postgresql${POSTGRES_MAJOR_VERSION} \
42+
pgedge-spock50_${POSTGRES_MAJOR_VERSION} \
43+
pgedge-postgresql${POSTGRES_MAJOR_VERSION}-contrib \
44+
pgedge-pgbackrest \
45+
pgedge-python3-psycopg2
46+
47+
# Install Patroni
48+
dnf install -y python3-pip
49+
pip install 'patroni[etcd,jsonlogger]==4.1.0'
50+
```
51+
52+
## Installing the RPM
53+
54+
Download the RPM for your architecture from the
55+
[GitHub releases page](https://github.com/pgedge/control-plane/releases). RPMs
56+
are available for both `amd64` and `arm64`.
57+
58+
Install the RPM with:
59+
60+
```sh
61+
rpm -i pgedge-control-plane-<version>.<arch>.rpm
62+
```
63+
64+
The RPM installs:
65+
66+
- `/usr/sbin/pgedge-control-plane` - the Control Plane binary
67+
- `/usr/lib/systemd/system/pgedge-control-plane.service` - the systemd service unit
68+
- `/etc/pgedge-control-plane/config.json` - the default configuration file
69+
70+
## Configuration
71+
72+
The default configuration file is located at
73+
`/etc/pgedge-control-plane/config.json`:
74+
75+
```json
76+
{
77+
"orchestrator": "systemd",
78+
"data_dir": "/var/lib/pgedge-control-plane"
79+
}
80+
```
81+
82+
The `orchestrator` field must be set to `"systemd"` for this installation
83+
method. The `data_dir` is where the Control Plane stores its state, including
84+
the embedded Etcd data.
85+
86+
The host ID defaults to the machine's short hostname. To set an explicit host
87+
ID, add a `host_id` field to the config file:
88+
89+
```json
90+
{
91+
"orchestrator": "systemd",
92+
"data_dir": "/var/lib/pgedge-control-plane",
93+
"host_id": "my-host-1"
94+
}
95+
```
96+
97+
## Starting the Control Plane
98+
99+
Start and enable the Control Plane service:
100+
101+
```sh
102+
systemctl enable --now pgedge-control-plane.service
103+
```
104+
105+
To check the service status:
106+
107+
```sh
108+
systemctl status pgedge-control-plane.service
109+
```
110+
111+
To tail the logs:
112+
113+
```sh
114+
journalctl -u pgedge-control-plane.service --follow
115+
```
116+
117+
## Initializing the Control Plane
118+
119+
Once the service is running on all hosts, initialize and join them the same way
120+
as a Docker Swarm installation.
121+
122+
Initialize the cluster on the first host:
123+
124+
```sh
125+
curl http://localhost:3000/v1/cluster/init
126+
```
127+
128+
The response contains a join token and server URL:
129+
130+
```json
131+
{
132+
"token": "PGEDGE-0c470f2eac35bb25135654a8dd9c812fc4aca4be8c8e34483c0e279ab79a7d30-907336deda459ebc79079babf08036fc",
133+
"server_url": "http://198.19.249.2:3000"
134+
}
135+
```
136+
137+
Join each additional host to the cluster by submitting a `POST` request to that
138+
host's `/v1/cluster/join` endpoint with the token and server URL from the
139+
previous step:
140+
141+
```sh
142+
curl -i -X POST http://<host_ip>:3000/v1/cluster/join \
143+
-H 'Content-Type: application/json' \
144+
--data '{
145+
"token": "PGEDGE-0c470f2eac35bb25135654a8dd9c812fc4aca4be8c8e34483c0e279ab79a7d30-907336deda459ebc79079babf08036fc",
146+
"server_url": "http://198.19.249.2:3000"
147+
}'
148+
```
149+
150+
Repeat for each host. Once all hosts have joined, you can interact with the API
151+
from any host in the cluster.
152+
153+
## Updating the Control Plane
154+
155+
To update to a newer version, download the new RPM from the
156+
[GitHub releases page](https://github.com/pgedge/control-plane/releases) and
157+
run:
158+
159+
```sh
160+
systemctl stop pgedge-control-plane.service
161+
rpm -U pgedge-control-plane-<new-version>.<arch>.rpm
162+
systemctl start pgedge-control-plane.service
163+
```
164+
165+
!!! note
166+
167+
The RPM upgrade (`rpm -U`) preserves your existing configuration file at
168+
`/etc/pgedge-control-plane/config.json` because it is marked as a
169+
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)