Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

fix(influxdb3): influxdb3 install package command syntax and details (#6512) 

* fix(influxdb3): override PLUGIN_DIR env var in compose services to match --plugin-dir

- Set INFLUXDB3_PLUGIN_DIR=/var/lib/influxdb3/plugins in both influxdb3-core and influxdb3-enterprise services
- Overrides Docker image default (/plugins) to match --plugin-dir command argument
- Ensures package installation works correctly with bind-mounted plugin directory
- Update influxdb3 install package CLI documentation with complete options reference

* docs(influxdb3): add Docker disk space troubleshooting for package installation

Add troubleshooting section for 'No space left on device' errors when installing packages in Docker environments. Includes commands to check Docker disk usage and clean up unused images and build cache.

Also fix Vale linting errors by changing 'URL' to 'url'.

* Apply suggestion from @jstirnaman

* fix(ci): Vale rules for URL/-url-/WAL/-wal-/Parquet/-parquet-:

  1. Simplified the Parquet vocabulary entry from the regex to just Parquet
  2. Added separate regex patterns for hyphenated identifiers

* feat(influxdb3): describe use cases and effects of --package-manager disabled
pull/6510/head^2
Jason Stirnaman 2025-11-05 00:04:44 -05:00 committed by GitHub
parent fe159e66c4
commit 089190dc60
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 412 additions and 272 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt
View File

@ -31,7 +31,8 @@ LogicalPlan
[Mm]onitor
MBs?
PBs?
Parquet|\b\w*-*parquet-\w*\b|\b--\w*parquet\w*\b|`[^`]*parquet[^`]*`
Parquet
\w*-?\w*parquet\w*-\w*
Redoc
SQLAlchemy
SQLAlchemy
@ -41,9 +42,11 @@ System.Data.Odbc
TBs?
\bUI\b
URL
\w*-?\w*url\w*-\w*
US (East|West|Central|North|South|Northeast|Northwest|Southeast|Southwest)
Unix
WALs?
\w*-?wal-\w*
Webpack
[pP]y.*\b
\b\w+_\w+\b
@ -82,7 +85,6 @@ quoteChar
retentionRules
sourceBucket
tagKey
url[s]?
v2
v3
venv

8
compose.yaml
View File

@ -334,6 +334,7 @@ services:
target: /var/lib/influxdb3/plugins/custom
environment:
- INFLUXDB3_AUTH_TOKEN=/run/secrets/influxdb3-core-admin-token
- INFLUXDB3_PLUGIN_DIR=/var/lib/influxdb3/plugins
secrets:
- influxdb3-core-admin-token
influxdb3-enterprise:
@ -357,14 +358,15 @@ services:
- --verbose
environment:
- INFLUXDB3_AUTH_TOKEN=/run/secrets/influxdb3-enterprise-admin-token
- INFLUXDB3_PLUGIN_DIR=/var/lib/influxdb3/plugins
volumes:
- type: bind
- type: bind
source: test/.influxdb3/enterprise/data
target: /var/lib/influxdb3/data
- type: bind
- type: bind
source: test/.influxdb3/plugins/influxdata
target: /var/lib/influxdb3/plugins
- type: bind
- type: bind
source: test/.influxdb3/enterprise/plugins
target: /var/lib/influxdb3/plugins/custom
secrets:

548
content/shared/influxdb3-cli/config-options.md
View File

File diff suppressed because it is too large Load Diff

122
content/shared/influxdb3-cli/install/package.md
View File

@ -1,54 +1,132 @@
The `influxdb3 install package` command installs Python packages for use in [InfluxDB 3 processing engine plugins](/influxdb3/version/process/).
The `influxdb3 install package` command installs Python packages within the plugin environment for use in [{{< product-name >}} processing engine plugins](/influxdb3/version/process/).
Use this command to add external dependencies that your plugins require, such as data processing libraries, notification tools, or forecasting packages.
## Usage
```bash { placeholders="PACKAGE_NAME" }
influxdb3 install package --packages PACKAGE_NAME
```bash
influxdb3 install package [OPTIONS] [PACKAGES]...
```
Replace the following:
## Arguments
- {{% code-placeholder-key %}}`PACKAGE_NAME`{{% /code-placeholder-key %}}: the name of the Python package to install
- **`[PACKAGES]...`**: One or more package names to install (space-separated)
## Options
| Option | Description | Default | Environment | Required |
|--------|-------------|---------|-------------|----------|
| `--packages` | Python package names to install (comma-separated) | | | |
| `-r`, `--requirements` | Path to requirements.txt file | | | |
| `-H`, `--host` | Host URL of the running {{< product-name >}} server | `http://127.0.0.1:8181` | `INFLUXDB3_HOST_URL` | |
| `--token` | The token for authentication with the InfluxDB 3 server | | `INFLUXDB3_AUTH_TOKEN` | |
| `--tls-ca` | Path to a custom TLS certificate authority for testing with self-signed certificates | | `INFLUXDB3_TLS_CA` | |
| `--plugin-dir` | Location of the plugins directory | | `INFLUXDB3_PLUGIN_DIR` | |
| `--virtual-env-location` | Location of the Python virtual environment | | `VIRTUAL_ENV` | |
| `--package-manager` | Package manager to use for installing packages | `discover` | | |
| Option | Description | Default | Environment Variable |
| :---------------------------------------------- | :------------------------------------------------------------------ | :---------------------- | :-------------------------- |
| `-H`, `--host <HOST_URL>` | The host URL of the running {{< product-name >}} server | `http://127.0.0.1:8181` | `INFLUXDB3_HOST_URL` |
| `--token <AUTH_TOKEN>` | The token for authentication with the {{< product-name >}} server | | `INFLUXDB3_AUTH_TOKEN` |
| `--plugin-dir <PLUGIN_DIR>` | Location of the plugins directory | `/plugins` | `INFLUXDB3_PLUGIN_DIR` |
| `--virtual-env-location <VIRTUAL_ENV_LOCATION>` | Custom virtual environment location | | `VIRTUAL_ENV` |
| `--package-manager <PACKAGE_MANAGER>` | Package manager to use: `discover`, `pip`, `uv`, or `disabled` | `discover` | `INFLUXDB3_PACKAGE_MANAGER` |
| `--plugin-repo <PLUGIN_REPO>` | Plugin repository URL | | `INFLUXDB3_PLUGIN_REPO` |
| `-r`, `--requirements <REQUIREMENTS>` | Path to a `requirements.txt` file | | |
| `--tls-ca <CA_CERT>` | Custom CA certificate for TLS (useful for self-signed certificates) | | `INFLUXDB3_TLS_CA` |
| `-h`, `--help` | Print help information | | |
| `--help-all` | Print detailed help information | | |
## Examples
### Install a single package
```bash { placeholders="pandas" }
influxdb3 install package --packages pandas
```bash
influxdb3 install package pandas
```
### Install multiple packages
```bash
influxdb3 install package --packages pandas,numpy,scipy
influxdb3 install package pint pandas requests
```
### Install packages from requirements file
### Install packages from a requirements file
```bash
influxdb3 install package -r requirements.txt
```
### Install with authentication
### Install packages with custom host and authentication
```bash { placeholders="AUTH_TOKEN|pandas" }
influxdb3 install package --token AUTH_TOKEN --packages pandas
```bash { placeholders="AUTH_TOKEN" }
influxdb3 install package \
--host http://localhost:8181 \
--token AUTH_TOKEN \
pint pandas
```
Replace the following:
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} for your {{< product-name >}} instance
### Install packages with a specific package manager
```bash
influxdb3 install package \
--package-manager uv \
prophet adtk
```
### Install packages with a custom CA certificate
```bash
influxdb3 install package \
--tls-ca /path/to/ca-cert.pem \
requests
```
## Package management
### Package manager selection
By default (`--package-manager discover`), the CLI automatically detects and uses the best available package manager:
1. **uv** (preferred): Faster package installation
2. **pip** (fallback): Standard Python package manager
### Virtual environment
The CLI manages a virtual environment for plugin packages to avoid conflicts with system Python packages.
You can customize the virtual environment location with `--virtual-env-location` or the `VIRTUAL_ENV` environment variable.
### Security mode
If your {{< product-name >}} server was started with [`--package-manager disabled`](/influxdb3/version/reference/config-options/#package-manager), the `influxdb3 install package` command is blocked for security and compliance requirements.
When attempting to install packages with this command while the server has package installation disabled, the command fails with a `403 Forbidden` error:
```
Package installation has been disabled. Contact your administrator for more information.
```
The server's `--package-manager disabled` setting is designed for:
- **Enterprise security requirements**: Prevent arbitrary package installation
- **Compliance environments**: Control exactly which packages are available
- **Air-gapped deployments**: Pre-install all dependencies before deployment
- **Multi-tenant scenarios**: Prevent tenants from installing potentially malicious packages
In these environments, administrators must pre-install all required Python packages into the server's virtual environment before starting {{< product-name >}}.
For more information, see the [`package-manager`](/influxdb3/version/reference/config-options/#package-manager) configuration option.
### Troubleshooting
If package installation fails:
- **Check if package installation is disabled**: If you receive a `403 Forbidden` error, contact your administrator. Package installation may be disabled on your {{< product-name >}} instance.
- **Verify network connectivity**: Ensure your {{< product-name >}} instance can reach PyPI or your custom package repository
- **Check package names**: Verify package names are correct and available in the package repository
- **Review logs**: Check {{< product-name >}} server logs for detailed error messages
- **Test with pip**: Try installing the package directly with `pip` to verify it's available
- **Use requirements file**: For complex dependencies, use a `requirements.txt` file with version pinning
- **Check Docker disk space** (Docker environments only): If running {{< product-name >}} in Docker and seeing "No space left on device" errors, free up disk space:
```bash
# Check Docker disk usage
docker system df
# Remove unused images and build cache
docker image prune -af
docker buildx prune -af
```