Skip to content

Commit e86a95b

Browse files
garylfowlerjstirnamansanderson
authored
Add Self-Signed Certificate docs (#6593)
* Add Self-Signed Certificate docs Added TLS/certificate verification options and updated container name for InfluxDB Explorer. * Update content/influxdb3/explorer/install.md * Update content/influxdb3/explorer/install.md * Update content/influxdb3/explorer/install.md * style(explorer): improve TLS and self-signed certificate documentation - Fix heading format: use lowercase "and" per style guidelines - Fix use case wording: "an internal or private CA" - Convert plain Note to callout format - Fix Docker command syntax error (remove erroneous line) - Reorganize: move self-signed certificates section under TLS - Add structured step-by-step instructions for self-signed certs - Wrap self-signed certificate example in expand-wrapper - Use consistent long-form Docker options (--volume, --env, --publish) - Update TOC with new subsections - Add NODE_EXTRA_CA_CERTS and CA_CERT_PATH to environment variables table - Add /ca-certs volume to volume reference table Addresses PR review feedback. * Apply suggestions from code review Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Apply suggestions from code review * Apply suggestion from @jstirnaman * Apply suggestion from @jstirnaman * Apply suggestion from @jstirnaman --------- Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com> Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
1 parent db9a727 commit e86a95b

File tree

1 file changed

+107
-2
lines changed

1 file changed

+107
-2
lines changed

content/influxdb3/explorer/install.md

Lines changed: 107 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ Use [Docker](https://docker.com) to install and run **InfluxDB 3 Explorer**.
1717
- [Persist data across restarts](#persist-data-across-restarts)
1818
- [Pre-configure InfluxDB connections](#pre-configure-influxdb-connections)
1919
- [Enable TLS/SSL (HTTPS)](#enable-tlsssl-https)
20+
- [TLS and certificate verification options](#tls-and-certificate-verification-options)
21+
- [Use self-signed certificates](#use-self-signed-certificates)
2022
- [Choose operational mode](#choose-operational-mode)
2123
- [Advanced configuration](#advanced-configuration)
2224
- [Environment variables](#environment-variables)
@@ -347,6 +349,105 @@ To enable TLS/SSL for secure connections:
347349
> [!Note]
348350
> The nginx web server automatically detects and uses certificate files in the mounted path.
349351
352+
#### TLS and certificate verification options
353+
#### TLS and certificate verification options
354+
355+
Use the following environment variables to configure TLS and certificate verification:
356+
357+
- `NODE_EXTRA_CA_CERTS` - Path to custom CA certificate file inside container (recommended).
358+
359+
This option adds an intermediate or custom CA certificate to the Node.js trusted certificate store
360+
and is required when InfluxDB uses certificates signed by an internal or private CA.
361+
362+
- **Format**: PEM format certificate file
363+
- **Example**: `-e NODE_EXTRA_CA_CERTS=/ca-certs/ca-bundle.crt`
364+
365+
> [!Note]
366+
> This is the native Node.js environment variable for custom CAs.
367+
368+
- `CA_CERT_PATH` - Alternative to `NODE_EXTRA_CA_CERTS` (convenience alias)
369+
- **Example**: `-e CA_CERT_PATH=/ca-certs/ca-bundle.crt`
370+
371+
> [!Note]
372+
> Use either `NODE_EXTRA_CA_CERTS` or `CA_CERT_PATH`; not both. `CA_CERT_PATH` aliases `NODE_EXTRA_CA_CERTS`.
373+
374+
#### Use self-signed certificates
375+
376+
To configure Explorer to trust self-signed or custom CA certificates when connecting to InfluxDB:
377+
378+
1. **Create a directory for CA certificates:**
379+
380+
```bash
381+
mkdir -p ./ca-certs
382+
```
383+
384+
2. **Copy your CA certificate to the directory:**
385+
386+
```bash
387+
cp /path/to/your-ca.pem ./ca-certs/
388+
```
389+
390+
3. **Mount the CA certificate directory and set the `NODE_EXTRA_CA_CERTS` environment variable:**
391+
392+
{{< expand-wrapper >}}
393+
{{% expand "View example Docker configuration for self-signed certificates" %}}
394+
395+
{{< code-tabs-wrapper >}}
396+
{{% code-tabs %}}
397+
[Docker](#)
398+
[Docker Compose](#)
399+
{{% /code-tabs %}}
400+
401+
{{% code-tab-content %}}
402+
{{< code-callout "NODE_EXTRA_CA_CERTS" >}}
403+
```bash
404+
docker run --detach \
405+
--name influxdb3-explorer \
406+
--restart unless-stopped \
407+
--publish 8888:443 \
408+
--volume $(pwd)/db:/db:rw \
409+
--volume $(pwd)/config:/app-root/config:ro \
410+
--volume $(pwd)/ssl:/etc/nginx/ssl:ro \
411+
--volume $(pwd)/ca-certs:/ca-certs:ro \
412+
--env SESSION_SECRET_KEY=your-secure-secret-key-here \
413+
--env NODE_EXTRA_CA_CERTS=/ca-certs/your-ca.pem \
414+
influxdata/influxdb3-ui:{{% latest-patch %}} \
415+
--mode=admin
416+
```
417+
{{< /code-callout >}}
418+
{{% /code-tab-content %}}
419+
420+
{{% code-tab-content %}}
421+
{{< code-callout "NODE_EXTRA_CA_CERTS" >}}
422+
```yaml
423+
# docker-compose.yml
424+
version: '3.8'
425+
426+
services:
427+
explorer:
428+
image: influxdata/influxdb3-ui:{{% latest-patch %}}
429+
container_name: influxdb3-explorer
430+
pull_policy: always
431+
command: ["--mode=admin"]
432+
ports:
433+
- "8888:443"
434+
volumes:
435+
- ./db:/db:rw
436+
- ./config:/app-root/config:ro
437+
- ./ssl:/etc/nginx/ssl:ro
438+
- ./ca-certs:/ca-certs:ro
439+
environment:
440+
SESSION_SECRET_KEY: ${SESSION_SECRET_KEY:-your-secure-secret-key-here}
441+
NODE_EXTRA_CA_CERTS: /ca-certs/your-ca.pem
442+
restart: unless-stopped
443+
```
444+
{{< /code-callout >}}
445+
{{% /code-tab-content %}}
446+
{{< /code-tabs-wrapper >}}
447+
448+
{{% /expand %}}
449+
{{< /expand-wrapper >}}
450+
350451
### Choose operational mode
351452
352453
{{% product-name %}} supports two operational modes:
@@ -410,6 +511,8 @@ services:
410511
| `DATABASE_URL` | `/db/sqlite.db` | Path to SQLite database inside container |
411512
| `SSL_CERT_PATH` | `/etc/nginx/ssl/cert.pem` | Path to SSL certificate file |
412513
| `SSL_KEY_PATH` | `/etc/nginx/ssl/key.pem` | Path to SSL private key file |
514+
| `NODE_EXTRA_CA_CERTS` | _(none)_ | Path to custom CA certificate file (PEM format) for trusting self-signed or internal CA certificates |
515+
| `CA_CERT_PATH` | _(none)_ | Alias for `NODE_EXTRA_CA_CERTS` |
413516
414517
> [!Important]
415518
> Always set `SESSION_SECRET_KEY` in production to persist user sessions across container restarts.
@@ -426,6 +529,7 @@ services:
426529
| `/db` | SQLite database storage | 700 | No (but recommended) |
427530
| `/app-root/config` | Connection configuration | 755 | No |
428531
| `/etc/nginx/ssl` | TLS/SSL certificates | 755 | Only for HTTPS |
532+
| `/ca-certs` | Custom CA certificates | 755 | Only for self-signed certificates |
429533
430534
### Port reference
431535
@@ -527,7 +631,7 @@ docker-compose up -d
527631
{{% code-tab-content %}}
528632
```bash
529633
docker run --rm \
530-
--name influxdb3-explorer-dev \
634+
--name influxdb3-explorer \
531635
--publish 8888:80 \
532636
influxdata/influxdb3-ui:{{% latest-patch %}}
533637
```
@@ -541,9 +645,10 @@ version: '3.8'
541645
services:
542646
explorer:
543647
image: influxdata/influxdb3-ui:{{% latest-patch %}}
544-
container_name: influxdb3-explorer-dev
648+
container_name: influxdb3-explorer
545649
ports:
546650
- "8888:80"
547651
```
548652
{{% /code-tab-content %}}
549653
{{< /code-tabs-wrapper >}}
654+

0 commit comments

Comments
 (0)