Skip to content

Commit 6c00d55

Browse files
travisamartintravisamartin
authored
Merge pull request #186 from nginx/internal/nim-185-lightweight-mode-docs
docs: add support for lightweight mode and clarify ClickHouse configu…
2 parents 9653f7b + d21b68b commit 6c00d55

File tree

14 files changed

+295
-231
lines changed

14 files changed

+295
-231
lines changed

‎content/includes/installation/clickhouse-defaults.md

Lines changed: 0 additions & 21 deletions
This file was deleted.

‎content/includes/nim/clickhouse/cli-skip-clickhouse.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
docs:
3+
files:
4+
- content/nim/deploy/vm-bare-metal/install.md
5+
- content/nim/disconnected/offline-install-guide.md
6+
---
7+
8+
{{< call-out "note" "Optional: Disable metrics collection" "" >}}
9+
To skip downloading and installing ClickHouse, add the `-s` flag to the script. This is useful if you do not plan to collect metrics.
10+
11+
If you skip ClickHouse, make sure to [disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}) in the `/etc/nms/nms.conf` configuration file after installing NGINX Instance Manager.
12+
{{< /call-out >}}

‎content/includes/nim/clickhouse/clickhouse-defaults.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
docs: DOCS-1238
3+
files:
4+
- content/nim/system-configuration/configure-clickhouse.md
5+
- content/nim/deploy/vm-bare-metal/install-nim-deprecated.md
6+
---
7+
8+
{{<bootstrap-table "table table-striped table-bordered">}}
9+
10+
| Configuration | Default | Notes |
11+
|------------------------------|------------------------------------|-------|
12+
| clickhouse.enable | true | Set to `false` to disable metrics collection and run NGINX Instance Manager in lightweight mode. Requires a service restart. |
13+
| clickhouse.address | tcp://localhost:9000 | The address of the ClickHouse database. |
14+
| clickhouse.username | | The username NGINX Instance Manager uses to connect to ClickHouse, if authentication is enabled. |
15+
| clickhouse.password | | The password for the specified ClickHouse user. |
16+
| clickhouse.tls_mode | false | Set to `true` to enable TLS for the ClickHouse connection. This setting will be deprecated in a future release. Use the `clickhouse.tls` section instead. |
17+
| clickhouse.tls.address | tcp://localhost:9440 | The address NGINX Instance Manager uses to connect to ClickHouse over TLS. Format: `<ip-address>:<port>`. |
18+
| clickhouse.tls.skip_verify | false | Set to `true` to skip TLS certificate verification. Use only for self-signed certificates in non-production environments. |
19+
| clickhouse.tls.key_path | | Path to the client TLS key file in PEM format. Required for client authentication. |
20+
| clickhouse.tls.cert_path | | Path to the client TLS certificate file in PEM format. Required for client authentication. |
21+
| clickhouse.tls.ca_path | /etc/ssl/certs/ca-certificates.crt | Path to the system Certificate Authority used to verify the server certificate. The default path works for Ubuntu and Debian. Use a CA bundle appropriate to your system. See [TLS configuration](#tls) for details. |
22+
23+
{{</bootstrap-table>}}

‎content/includes/nim/clickhouse/clickhouse-install.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
docs:
3+
files:
4+
- content/nim/deploy/vm-bare-metal/install-nim-deprecated.md
5+
---
6+
7+
NGINX Instance Manager uses [ClickHouse](https://clickhouse.com) to store metrics, events, alerts, and configuration settings.
8+
9+
{{< call-out "important" "ClickHouse configuration requirements" "" >}}
10+
If you install ClickHouse and choose to set a password (the default is an empty string), you must add it to the `clickhouse.password` setting in the `/etc/nms/nms.conf` file. If the password is missing or incorrect, NGINX Instance Manager will not start.
11+
12+
For instructions and additional configuration options, including TLS settings, see [Configure ClickHouse]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}).
13+
{{< /call-out >}}
14+
15+
{{< call-out "note" "ClickHouse version requirement" "" >}}NGINX Instance Manager requires ClickHouse version {{< clickhouse-version >}} or later.
16+
{{< /call-out >}}
17+
18+
Follow these steps to install and enable ClickHouse on supported Linux distributions.
19+
20+
1. First, set up the repository.
21+
22+
- For RPM-based systems (CentOS, RHEL):
23+
24+
```shell
25+
sudo yum install -y yum-utils
26+
sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo
27+
```
28+
29+
- For Debian-based systems (Debian, Ubuntu):
30+
31+
```shell
32+
sudo apt-get install -y apt-transport-https ca-certificates dirmngr
33+
GNUPGHOME=$(mktemp -d)
34+
sudo GNUPGHOME="$GNUPGHOME" gpg --no-default-keyring --keyring /usr/share/keyrings/clickhouse-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 8919F6BD2B48D754
35+
sudo rm -r "$GNUPGHOME"
36+
sudo chmod +r /usr/share/keyrings/clickhouse-keyring.gpg
37+
38+
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb lts main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
39+
sudo apt-get update
40+
```
41+
42+
2. Next, install the ClickHouse server and client:
43+
44+
- For RPM-based systems (CentOS, RHEL):
45+
46+
```shell
47+
sudo yum install -y clickhouse-server clickhouse-client
48+
```
49+
50+
- For Debian-based systems (Debian, Ubuntu):
51+
52+
```shell
53+
sudo apt-get install -y clickhouse-server clickhouse-client
54+
```
55+
56+
3. Then, enable the ClickHouse service so it starts automatically on reboot:
57+
58+
```shell
59+
sudo systemctl enable clickhouse-server
60+
```
61+
62+
4. Start the ClickHouse service:
63+
64+
```shell
65+
sudo systemctl start clickhouse-server
66+
```
67+
68+
5. Finally, confirm the service is running:
69+
70+
```shell
71+
sudo systemctl status clickhouse-server
72+
```

‎content/includes/nim/installation/optional-steps/configure-clickhouse.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
docs:
3+
files:
4+
- content/nim/deploy/vm-bare-metal/install.md
5+
- content/nim/deploy/vm-bare-metal/install-nim-deprecated.md
6+
- content/nim/disconnected/offline-install-guide.md
7+
- content/nim/disconnected/offline-install-guide-deprecated.md
8+
---
9+
10+
If you installed ClickHouse and set a password (the default is an empty string), you must add it to the `clickhouse.password` setting in the `/etc/nms/nms.conf` file after installing NGINX Instance Manager. If the password is missing or incorrect, NGINX Instance Manager will not start.
11+
12+
You can also configure additional ClickHouse settings in the same section:
13+
14+
- `clickhouse.username` – the username used to connect to ClickHouse
15+
- `clickhouse.address` – the address of the ClickHouse server (default is `tcp://localhost:9000`)
16+
- `clickhouse.tls_mode` – set to `true` to enable TLS
17+
- TLS certificate settings, such as:
18+
- `clickhouse.tls.cert_path`
19+
- `clickhouse.tls.key_path`
20+
- `clickhouse.tls.ca_path`
21+
- `clickhouse.tls.skip_verify`
22+
23+
For more details, see [Configure ClickHouse]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}).

‎content/includes/nim/installation/optional-steps/configure-selinux.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
docs:
3+
files:
4+
- content/nim/deploy/vm-bare-metal/install-nim-deprecated.md
5+
- content/nim/deploy/vm-bare-metal/install.md
6+
- content/nim/disconnected/offline-install-guide-deprecated.md
7+
- content/nim/disconnected/offline-install-guide.md
8+
---
9+
10+
SELinux helps secure your deployment by enforcing mandatory access control policies.
11+
12+
If you use SELinux, follow the steps in the [Configure SELinux]({{< ref "/nim/system-configuration/configure-selinux.md" >}}) guide to restore SELinux contexts (`restorecon`) for the files and directories related to NGINX Instance Manager.

‎content/includes/nim/installation/optional-steps/disable-metrics-collection.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
docs:
3+
files:
4+
- content/nim/deploy/vm-bare-metal/install.md
5+
- content/nim/disconnected/offline-install-guide-deprecated.md
6+
- content/nim/disconnected/offline-install-guide.md
7+
---
8+
9+
If you are not collecting metrics—either because you did not install ClickHouse or no longer want to use it—you must disable metrics collection by editing the `/etc/nms/nms.conf` file.
10+
11+
For instructions, see [Disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}).

‎content/includes/nim/installation/optional-steps/install-configure-vault.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
docs:
3+
files:
4+
- content/nim/deploy/vm-bare-metal/install-nim-deprecated.md
5+
- content/nim/deploy/vm-bare-metal/install.md
6+
- content/nim/disconnected/offline-install-guide-deprecated.md
7+
- content/nim/disconnected/offline-install-guide.md
8+
---
9+
10+
NGINX Instance Manager can use [Vault](https://www.vaultproject.io/) as a datastore for secrets.
11+
12+
To install and enable Vault, follow these steps:
13+
14+
- Follow Vault's instructions to [install Vault 1.8.8 or later](https://www.vaultproject.io/docs/install) for your distribution.
15+
- Ensure you're running Vault in a [production-hardened environment](https://learn.hashicorp.com/tutorials/vault/production-hardening).
16+
- After installing NGINX Instance Manager, follow the steps to [configure Vault for storing secrets]({{< ref "/nim/system-configuration/configure-vault.md" >}}).

‎content/nim/deploy/vm-bare-metal/install-nim-deprecated.md

Lines changed: 25 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -83,113 +83,25 @@ Install NGINX Open Source or NGINX Plus on the host where you'll install NGINX I
8383

8484
---
8585

86-
## Install ClickHouse {#install-clickhouse}
86+
## Configure metrics collection
8787

88-
{{<note>}}NGINX Instance Manager requires ClickHouse 22.3.15.33 or later.{{</note>}}
88+
### Disable metrics collection
8989

90-
NGINX Instance Manager uses [ClickHouse](https://clickhouse.com) to store metrics, events, and alerts, as well as configuration settings.
90+
NGINX Instance Manager uses ClickHouse to store metrics, events, alerts, and configuration data.
9191

92-
Select the tab for your Linux distribution, then follow the instructions to install ClickHouse.
92+
If you do not need to store metrics, you can skip the installation steps in this section. Instead, you must disable metrics collection in the `/etc/nms/nms.conf` configuration file.
9393

94-
{{<tabs name="clickhouse">}}
94+
For instructions, see [Disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}).
9595

96-
{{%tab name="CentOS, RHEL, RPM-Based"%}}
97-
98-
To install and enable ClickHouse CentOS, RHEL, and RPM-Based distributions, take the following steps:
99-
100-
1. Set up the repository:
101-
102-
``` bash
103-
sudo yum install -y yum-utils
104-
sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo
105-
```
106-
107-
1. Install the ClickHouse server and client:
108-
109-
```bash
110-
sudo yum install -y clickhouse-server clickhouse-client
111-
```
112-
113-
> <span style="color: #c20025;"><i class="fas fa-exclamation-triangle"></i> **IMPORTANT!**</span> When installing ClickHouse, you have the option to specify a password or leave the password blank (the default is an empty string). If you choose to specify a password for ClickHouse, you must also edit the `/etc/nms/nms.conf` file after installing NGINX Instance Manager and enter your ClickHouse password; otherwise, NGINX Instance Manager won't start.
114-
>
115-
> For more information on customizing ClickHouse settings, refer to the [Configure ClickHouse]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}) topic.
116-
117-
1. Enable ClickHouse so that it starts automatically if the server is restarted:
118-
119-
```bash
120-
sudo systemctl enable clickhouse-server
121-
```
122-
123-
1. Start the ClickHouse server:
124-
125-
```bash
126-
sudo systemctl start clickhouse-server
127-
```
128-
129-
1. Verify ClickHouse is running:
130-
131-
```bash
132-
sudo systemctl status clickhouse-server
133-
```
134-
135-
{{%/tab%}}
136-
137-
{{%tab name="Debian, Ubuntu, Deb-Based"%}}
138-
139-
To install and enable ClickHouse on Debian, Ubuntu, and Deb-Based distributions, take the following steps:
140-
141-
1. Set up the repository:
142-
143-
```bash
144-
sudo apt-get install -y apt-transport-https ca-certificates dirmngr
145-
GNUPGHOME=$(mktemp -d)
146-
sudo GNUPGHOME="$GNUPGHOME" gpg --no-default-keyring --keyring /usr/share/keyrings/clickhouse-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 8919F6BD2B48D754
147-
sudo rm -r "$GNUPGHOME"
148-
sudo chmod +r /usr/share/keyrings/clickhouse-keyring.gpg
149-
150-
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb lts main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
151-
sudo apt-get update
152-
```
96+
### Install ClickHouse to enable metrics
15397

154-
1. Install the ClickHouse server and client:
98+
{{< include "nim/clickhouse/clickhouse-install.md" >}}
15599

156-
``` bash
157-
sudo apt-get install -y clickhouse-server clickhouse-client
158-
```
159-
160-
> <span style="color: #c20025;"><i class="fas fa-exclamation-triangle"></i> **IMPORTANT!**</span> When installing ClickHouse, you have the option to specify a password or leave the password blank (the default is an empty string). If you choose to specify a password for ClickHouse, you must also edit the `/etc/nms/nms.conf` file after installing NGINX Instance Manager and enter your ClickHouse password; otherwise, NGINX Instance Manager won't start.
161-
>
162-
> For more information on customizing ClickHouse settings, refer to the [Configure ClickHouse]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}) topic.
100+
#### ClickHouse Default Settings
163101

164-
1. Enable ClickHouse so that it starts automatically if the server is restarted:
102+
NGINX Instance Manager uses the following default values for ClickHouse. To change these values, see the [Configure ClickHouse](nim/system-configuration/configure-clickhouse.md) guide.
165103

166-
```bash
167-
sudo systemctl enable clickhouse-server
168-
```
169-
170-
1. Start the ClickHouse server:
171-
172-
``` bash
173-
sudo systemctl start clickhouse-server
174-
```
175-
176-
1. Verify ClickHouse is running:
177-
178-
```bash
179-
sudo systemctl status clickhouse-server
180-
```
181-
182-
{{%/tab%}}
183-
184-
{{</tabs>}}
185-
186-
### ClickHouse Default Settings
187-
188-
NGINX Instance Manager uses the following default values for ClickHouse:
189-
190-
{{<important>}}You can customize these settings. However, if you use custom settings, make sure to follow the [Configure ClickHouse]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}) instructions to update the `nms.conf` file after you've installed NGINX Instance Manager; otherwise NGINX Instance Manager won't be able to connect to ClickHouse.{{</important>}}
191-
192-
{{< include "installation/clickhouse-defaults.md" >}}
104+
{{< include "nim/clickhouse/clickhouse-defaults.md" >}}
193105

194106
---
195107

@@ -258,16 +170,27 @@ To install NGINX Instance Manager, you need to add the official repository to pu
258170
sudo systemctl restart nginx
259171
```
260172

261-
### Post-Installation Steps
173+
## Optional post-installation steps
174+
175+
### Configure ClickHouse
176+
177+
{{< include "nim/installation/optional-steps/configure-clickhouse.md" >}}
178+
179+
### Install and configure Vault {#install-vault}
180+
181+
{{< include "nim/installation/optional-steps/install-configure-vault.md" >}}
182+
183+
184+
### Configure SELinux
262185

263-
{{< include "installation/optional-installation-steps.md" >}}
186+
{{< include "nim/installation/optional-steps/configure-selinux.md" >}}
264187

265-
### Accessing the Web Interface
188+
## Accessing the Web Interface
266189

267190
{{< include "installation/access-web-ui.md" >}}
268191

269192

270-
### Add License
193+
## Add License
271194

272195
{{< include "nim/admin-guide/license/connected-install-license-note.md" >}}
273196

0 commit comments

Comments
 (0)