Skip to content

Commit 4ad4441

Browse files
tuxmeatuxmea
authored
Merge pull request #148 from miharp/feat/modernize-openvox-server-install
Modernize openvox-server install docs into structured section
2 parents e1f9512 + 206d81b commit 4ad4441

5 files changed

Lines changed: 276 additions & 78 deletions

File tree

‎_data/nav/openvox-server_8x.yml‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,16 @@
99
link: deprecated_features.html
1010
- text: Compatibility with Puppet agent
1111
link: compatibility_with_puppet_agent.html
12-
- text: Installing Puppet Server
13-
link: install_from_packages.html
12+
- text: Installing and upgrading
13+
items:
14+
- text: Before you begin
15+
link: install_pre.html
16+
- text: Install OpenVox Server
17+
link: install_from_packages.html
18+
- text: What gets installed and where
19+
link: install_what_and_where.html
20+
- text: Upgrading OpenVox Server
21+
link: upgrade_minor.html
1422
- text: Configuring Puppet Server
1523
items:
1624
- text: Configuring Puppet Server

‎docs/_openvox-server_8x/install_from_packages.markdown‎

Lines changed: 49 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,73 @@
11
---
22
layout: default
3-
title: "Install Puppet Server"
4-
canonical: "/puppetserver/latest/install_from_packages.html"
3+
title: "Install OpenVox Server"
54
---
65

7-
[repodocs]: https://puppet.com/docs/puppet/latest/puppet_platform.html
6+
[prereqs]: ./install_pre.html
7+
[tuning]: ./tuning_guide.html
8+
[install_linux]: /openvox/latest/install_linux.html
9+
[openvoxdb]: /openvoxdb/latest/install_via_module.html
10+
[downloads_page]: https://voxpupuli.org/openvox/install/
811

9-
Puppet Server is a required application that runs on the Java Virtual Machine (JVM). It controls the configuration information for one or more managed agent nodes.
12+
Install `openvox-server` on the host that will act as the Puppet CA and catalog
13+
compiler for your infrastructure.
1014

11-
> Note: If you have any issues with the steps below, submit these to our [bug tracker](https://tickets.puppet.com/browse/SERVER).
15+
**Before you begin:** Review the [pre-install tasks][prereqs] to confirm your
16+
platform is supported, your Java version is correct, and port 8140 is open.
1217

13-
## Before you begin
18+
1. Enable the OpenVox repository for your distribution.
1419

15-
Review the supported operating systems and make sure you have a supported version of Java.
20+
On apt-based systems, download and install the release package for your OS from
21+
[apt.voxpupuli.org](https://apt.voxpupuli.org). For example, on Ubuntu 22.04:
1622

17-
### Supported operating systems
23+
```bash
24+
wget https://apt.voxpupuli.org/openvox8-release-ubuntu22.04.deb
25+
sudo dpkg -i openvox8-release-ubuntu22.04.deb
26+
sudo apt update
27+
```
1828

19-
Puppet provides official packages that install Puppet Server 6 and all of its prerequisites on x86_64 architectures for the following platforms:
29+
On yum/dnf-based systems, install the release package for your OS from
30+
[yum.voxpupuli.org](https://yum.voxpupuli.org). For example, on EL 9:
2031

21-
* Red Hat Enterprise Linux 6, 7
22-
* Debian 8 (Jessie), 9 (Stretch), 10 (Buster)
23-
* Ubuntu 16.04 (Xenial), 18.04 (Bionic)
24-
* SLES 12 SP1
32+
```bash
33+
sudo rpm -Uvh https://yum.voxpupuli.org/openvox8-release-el-9.noarch.rpm
34+
```
2535

26-
### Java support
36+
For the full list of supported distributions and release packages, see the
37+
[Installing OpenVox][downloads_page] page.
2738

28-
Puppet Server versions are tested against the following versions of Java:
39+
2. Install the package.
2940

30-
| Puppet Server | Java |
31-
|---|---|
32-
| 2.x | 7, 8 |
33-
| 5.x | 8 |
34-
| 6.0-6.5 | 8, 11 (experimental) |
35-
| 6.6 and later | 8, 11 |
41+
On apt-based systems:
3642

37-
Some Java versions may work with other Puppet Server versions, but we do not test or support those cases. Community submitted patches for support greater than Java 11 are welcome. Both Java 8 and 11 are considered long-term support versions and are planned to be supported by upstream maintainers until 2022 or later.
43+
```bash
44+
sudo apt install openvox-server
45+
```
3846

39-
> Note: Java 8 runtime packages do not exist in the standard repositories for Debian 8 (Jessie) or Ubuntu 18.04 (Bionic). To install Puppet Server on Jessie, [configure the `jessie-backports` repository](https://backports.debian.org/Instructions/). To install Puppet Server on Bionic, enable the [universe repository](https://help.ubuntu.com/community/Repositories/Ubuntu).
47+
On yum/dnf-based systems:
4048

41-
## Install Puppet Server
49+
```bash
50+
sudo yum install openvox-server
51+
```
4252

43-
Puppet Server is configured to use 2 GB of RAM by default. If you're just testing an installation on a Virtual Machine, this much memory is not necessary. To change the memory allocation, see [Running Puppet Server on a VM](#Running-Puppet-Server-on-a-VM).
53+
3. Start and enable the service.
4454

45-
1. [Enable the Puppet package repositories][repodocs], if you haven't already done so.
55+
```bash
56+
sudo systemctl start puppetserver
57+
sudo systemctl enable puppetserver
58+
```
4659

47-
2. Install the Puppet Server package by running one of the following commands.
60+
4. Verify the installation.
4861

49-
Red Hat operating systems:
62+
```bash
63+
puppetserver --version
64+
sudo systemctl status puppetserver
65+
```
5066

51-
````
52-
yum install puppetserver
53-
````
67+
The service should be active and you should see a version string printed.
5468

55-
Debian and Ubuntu:
69+
## What to do next
5670

57-
```
58-
apt-get install puppetserver
59-
```
60-
61-
There is no `-` in the package name.
62-
63-
> Note: If you're upgrading, stop any existing `puppetmaster` or `puppetserver` service by running `service <service_name> stop` or `systemctl stop <service_name>`.
64-
65-
3. Start the Puppet Server service:
66-
67-
```
68-
sudo systemctl start puppetserver
69-
```
70-
71-
4. To check you have installed the Puppet Server package correctnly, run the following command to check the version:
72-
73-
```
74-
puppetserver -v
75-
```
76-
77-
### What to do next
78-
79-
Now that Puppet Server is installed, move on to these next steps:
80-
81-
1. [Install a Puppet agent](https://puppet.com/docs/puppet/latest/install_agents.html)
82-
2. [Install PuppetDB](https://puppet.com/docs/puppetdb/latest/install_via_module.html) (optional) ⁠— if you would like to to enable extra features, including enhanced queries and reports about your infrastructure.
83-
84-
## Running Puppet Server on a VM
85-
86-
By default, Puppet Server is configured to use 2GB of RAM. However, if you want to experiment with Puppet Server on a VM, you can safely allocate as little as 512MB of memory. To change the Puppet Server memory allocation, you can edit the init config file.
87-
88-
* For RHEL or CentOS, open `/etc/sysconfig/puppetserver`
89-
* For Debian or Ubuntu, open `/etc/default/puppetserver`
90-
91-
1. In your settings, update the line:
92-
93-
# Modify this if you'd like to change the memory allocation, enable JMX, etc
94-
JAVA_ARGS="-Xms2g -Xmx2g"
95-
96-
Replace 2g with the amount of memory you want to allocate to Puppet Server. For example, to allocate 1GB of memory, use `JAVA_ARGS="-Xms1g -Xmx1g"`; for 512MB, use `JAVA_ARGS="-Xms512m -Xmx512m"`.
97-
98-
For more information about the recommended settings for the JVM, see [Oracle's docs on JVM tuning.](http://docs.oracle.com/cd/E15523_01/web.1111/e13814/jvm_tuning.htm)
99-
100-
2. Restart the `puppetserver` service after making any changes to this file.
71+
- [Install OpenVox agent on Linux][install_linux] — roll out agents to managed nodes.
72+
- [Install OpenVoxDB][openvoxdb] (optional) — enables enhanced queries and reports about your infrastructure.
73+
- Review the [tuning guide][tuning] if you need to adjust the default 2 GB JVM heap size.

‎docs/_openvox-server_8x/install_pre.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
layout: default
3+
title: "Installing OpenVox Server: Before you begin"
4+
---
5+
6+
[architecture]: /openvox/latest/architecture.html
7+
8+
Before installing OpenVox Server:
9+
10+
1. Confirm your platform is supported.
11+
12+
OpenVox Server is a Linux-only service. Packages are available from the OpenVox
13+
repositories at [apt.voxpupuli.org](https://apt.voxpupuli.org) and
14+
[yum.voxpupuli.org](https://yum.voxpupuli.org).
15+
16+
**apt-based systems:**
17+
18+
| Distribution | Versions |
19+
| ------------ | -------- |
20+
| Debian | 10, 11, 12, 13 |
21+
| Ubuntu | 18.04, 20.04, 22.04, 24.04, 25.04, 26.04 |
22+
23+
**yum/dnf-based systems:**
24+
25+
| Distribution | Versions | Architectures |
26+
| ------------ | -------- | ------------- |
27+
| EL (RHEL, AlmaLinux, Rocky Linux, CentOS) | 7 | x86_64 |
28+
| EL (RHEL, AlmaLinux, Rocky Linux, CentOS) | 8, 9 | x86_64, aarch64, ppc64le |
29+
| EL (RHEL, AlmaLinux, Rocky Linux, CentOS) | 10 | x86_64, aarch64 |
30+
| Amazon Linux | 2, 2023 | x86_64, aarch64 |
31+
| Fedora | 36, 40, 41, 42, 43 | x86_64, aarch64 |
32+
| SLES | 15, 16 | x86_64, aarch64 |
33+
| RHEL FIPS | 8, 9 | x86_64, aarch64 |
34+
35+
2. Verify your Java version.
36+
37+
OpenVox Server requires Java 17 or 21. Install a supported JDK from your
38+
distribution's repositories before installing the OpenVox Server package. OpenVox
39+
Server does not bundle a JDK.
40+
41+
3. Plan memory allocation.
42+
43+
OpenVox Server is configured to use 2 GB of RAM by default. Make sure the host
44+
has enough available memory. For testing on a VM, you can reduce this to 512 MB
45+
after installation — see the [tuning guide](./tuning_guide.html).
46+
47+
4. Open the required port.
48+
49+
OpenVox agents connect to the server on TCP port **8140**. Make sure this port is
50+
reachable from all managed nodes. If you are using a firewall, open it before
51+
starting the service.
52+
53+
5. Verify DNS.
54+
55+
By default, agents look for the server at the hostname `puppet`. Make sure that
56+
name resolves correctly on the network, or plan to set the `server` setting in
57+
`puppet.conf` on each agent explicitly.
58+
59+
6. Synchronize clocks.
60+
61+
OpenVox uses SSL certificates with time-based validity. If the clocks on the
62+
server and agent nodes differ by more than a few minutes, certificate validation
63+
will fail and agents will be unable to connect. Make sure NTP or a similar time
64+
synchronization service is running on all nodes before deploying.
65+
66+
7. Install and validate OpenVox Server before rolling out agents.
67+
68+
In an agent-server deployment, the server must be running and reachable before
69+
agents can check in. See the [architecture overview][architecture] for background
70+
on deployment models.
71+
72+
Once you have completed these checks, continue with [Install OpenVox Server](./install_from_packages.html).

‎docs/_openvox-server_8x/install_what_and_where.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
layout: default
3+
title: "What gets installed and where (OpenVox Server)"
4+
---
5+
6+
When you install the `openvox-server` package, it places files and directories in the following locations.
7+
8+
## Executables and binaries
9+
10+
| Location | Description |
11+
| -------- | ----------- |
12+
| `/opt/puppetlabs/bin/puppetserver` | Main `puppetserver` executable |
13+
| `/opt/puppetlabs/bin/puppet` | Puppet CLI (installed by the `openvox-agent` dependency) |
14+
| `/opt/puppetlabs/server/bin/` | `puppetserver` and `puppetdb` binaries — not on `PATH` by default |
15+
| `/opt/puppetlabs/puppet/bin/` | Private Ruby runtime and agent binaries |
16+
17+
## Configuration files
18+
19+
OpenVox Server uses two configuration directories:
20+
21+
**Server configuration** (`/etc/puppetlabs/puppetserver/`):
22+
23+
| File | Description |
24+
| ---- | ----------- |
25+
| `conf.d/puppetserver.conf` | Main server settings |
26+
| `conf.d/webserver.conf` | Jetty web server settings |
27+
| `conf.d/web-routes.conf` | Web application mount points |
28+
| `conf.d/auth.conf` | HTTPS access control rules |
29+
| `conf.d/ca.conf` | Certificate authority service settings |
30+
| `conf.d/global.conf` | Global settings |
31+
| `conf.d/metrics.conf` | Metrics service settings |
32+
| `logback.xml` | Log level and output configuration |
33+
| `ca/` | CA certificates, CRL, signed certs, and CSRs (`cadir`) |
34+
35+
**Puppet configuration** (`/etc/puppetlabs/puppet/`):
36+
37+
| File | Description |
38+
| ---- | ----------- |
39+
| `puppet.conf` | Main Puppet configuration — server settings go in the `[server]` section |
40+
| `ssl/` | Server node certificate, private key, and CRL (`ssldir`) |
41+
| `hiera.yaml` | Hiera lookup configuration |
42+
43+
## Code directory
44+
45+
Puppet manifests and modules live under `/etc/puppetlabs/code/`. This is the
46+
[codedir](/openvox/latest/dirs_codedir.html) used by the server when compiling catalogs.
47+
48+
## Runtime data
49+
50+
| Path | Description |
51+
| ---- | ----------- |
52+
| `/opt/puppetlabs/server/data/puppetserver/` | Server runtime data (reports, state, JRuby gems, yaml cache) |
53+
| `/var/run/puppetlabs/puppetserver/` | PID file |
54+
55+
## Log files
56+
57+
| Path | Description |
58+
| ---- | ----------- |
59+
| `/var/log/puppetlabs/puppetserver/puppetserver.log` | Main server log |
60+
| `/var/log/puppetlabs/puppetserver/puppetserver-access.log` | HTTP access log |
61+
| `/var/log/puppetlabs/puppetserver/puppetserver-status.log` | Status service log |
62+
63+
## Service
64+
65+
OpenVox Server runs as the `puppetserver` service, managed by systemd.
66+
67+
| Property | Value |
68+
| -------- | ----- |
69+
| Service name | `puppetserver` |
70+
| Runs as user | `puppet` (created by the package installer) |
71+
| JVM heap config | `/etc/sysconfig/puppetserver` (EL) or `/etc/default/puppetserver` (Debian/Ubuntu) |
72+
73+
## Migrating from Puppet Server packages
74+
75+
OpenVox Server uses the same directory layout as Puppet Server. If you are replacing
76+
legacy Puppet Server packages:
77+
78+
- Back up `/etc/puppetlabs/` and `/opt/puppetlabs/server/data/` before you begin.
79+
- Expect the same command names, configuration paths, and service name after installation.
80+
- Do not install Puppet Server and OpenVox Server packages side by side on the same host.

‎docs/_openvox-server_8x/upgrade_minor.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
layout: default
3+
title: "Upgrading OpenVox Server"
4+
---
5+
6+
Use this page for routine OpenVox Server upgrades and for in-place migrations from
7+
legacy Puppet Server packages to OpenVox Server packages.
8+
9+
OpenVox Server is functionally equivalent to modern Puppet Server. A host cannot have
10+
both Puppet Server and OpenVox Server packages installed at the same time. Back up
11+
`/etc/puppetlabs/` and `/var/opt/puppetlabs/` before you start.
12+
13+
## Recommended upgrade order
14+
15+
In an agent-server deployment, upgrade infrastructure components in this order:
16+
17+
1. `openvox-server`
18+
2. `openvoxdb`
19+
3. `openvoxdb-termini` on server nodes
20+
4. `openvox-agent` on managed nodes
21+
22+
Keeping the server ahead of the agents it serves avoids compatibility issues during
23+
the upgrade window.
24+
25+
## Upgrading Linux packages
26+
27+
On apt-based systems:
28+
29+
```bash
30+
sudo apt update
31+
sudo apt install --only-upgrade openvox-server
32+
```
33+
34+
On yum/dnf-based systems:
35+
36+
```bash
37+
sudo yum update openvox-server
38+
```
39+
40+
After upgrading the server, restart the service to load the new version:
41+
42+
```bash
43+
sudo systemctl restart puppetserver
44+
sudo systemctl status puppetserver
45+
```
46+
47+
## Migrating from legacy Puppet Server packages
48+
49+
If you are replacing Puppet Server rather than upgrading an existing OpenVox
50+
installation, enable the OpenVox repository first:
51+
52+
1. Enable the OpenVox repository for your platform — see [OpenVox repositories and packages](/openvox/latest/openvox_platform.html).
53+
2. Install `openvox-server`. The package manager will replace the legacy Puppet Server package.
54+
3. Restore `/etc/puppetlabs/` from your backup if any configuration was lost.
55+
4. Start the service and validate.
56+
57+
## After the upgrade
58+
59+
After upgrading:
60+
61+
1. Confirm the service is running: `sudo systemctl status puppetserver`
62+
2. Check the server log for errors: `sudo journalctl -u puppetserver -n 50`
63+
3. Run a test agent check-in from a managed node: `sudo puppet agent --test`
64+
4. Verify certificate handling and OpenVoxDB connectivity where applicable.
65+
5. Review the [release notes](./release_notes.html) for version-specific changes.

0 commit comments

Comments
 (0)