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
2025-11-04 16:30:00 -06:00 · 2025-11-04 16:30:00 -06:00 · 759991af56
parent d7233aa93f
commit 759991af56
2 changed files with 73 additions and 25 deletions
--- a/compose.yaml
+++ b/compose.yaml
@ -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:
--- a/content/shared/influxdb3-cli/install/package.md
+++ b/content/shared/influxdb3-cli/install/package.md
@ -1,54 +1,100 @@
-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 pint
 ```

 ### 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.
+
+### Troubleshooting
+
+If package installation fails:
+
+1. **Verify network connectivity**: Ensure your {{< product-name >}} instance can reach PyPI or your custom package repository
+2. **Check package names**: Verify package names are correct and available in the package repository
+3. **Review logs**: Check {{< product-name >}} server logs for detailed error messages
+4. **Test with pip**: Try installing the package directly with `pip` to verify it's available
+5. **Use requirements file**: For complex dependencies, use a `requirements.txt` file with version pinning