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

5204 v2 update downloads and install instructions (#5214) 

* chore(ci): Docker install gpg and wget for test image.

* chore(ci): add a config (temporary) for v2 tests.

* chore(ci): tests: replace latest-patch tag with environment variable.

* chore(ci): test runner

- test.sh diffs against origin/master
- test.sh builds the image for each run and then removes the container after the run.
- tesh.sh adds examples for running and debugging to remind myself.
- compose.yaml adds a bind mount to copy docs-v2/data into docs-v2/test.
- Dockerfile: simplify path use
- run-tests.sh: make default run less verbose, add support for a verbose option (and future options).
- run-tests.sh: generates a .env.products file from data/products.yml and sources the file variables as environment variables to use in test runs.
- run-tests.sh: adds some misc. test setup.
- requirements.txt: return to using the influxdb3-python release

* chore(v2): Update and test v2 OSS and CLI install instructions:

- Update download URLs and paths for all distributions.
- Update and fix install instructions, make consistent between browser downloading and shell
- Make testable.

* chore(v2): Ignore parse_yaml.sh download.
pull/5216/head
Jason Stirnaman 2023-11-06 09:48:01 -06:00 committed by GitHub
parent dc4a9a9318
commit 6067315a58
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 436 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
Dockerfile
View File

@ -3,17 +3,23 @@
# If you need more help, visit the Dockerfile reference guide at
# https://docs.docker.com/engine/reference/builder/
ARG PYTHON_VERSION=3.11.5
FROM python:${PYTHON_VERSION}-slim as base
FROM python:3.12.0-slim-bookworm
RUN apt-get update && apt-get install -y \
curl \
git \
gpg \
wget \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /usr/src/app
ARG SOURCE_DIR
ARG TESTS_DIR
COPY test ./test
COPY data ./test/data
RUN chmod -R 755 .
# Prevents Python from writing pyc files.
ENV PYTHONDONTWRITEBYTECODE=1
@ -22,26 +28,23 @@ ENV PYTHONDONTWRITEBYTECODE=1
# the application crashes without emitting any logs due to buffering.
ENV PYTHONUNBUFFERED=1
COPY $SOURCE_DIR /app/$SOURCE_DIR
WORKDIR /usr/src/app/${SOURCE_DIR}
WORKDIR /app/$SOURCE_DIR
RUN chmod -R 755 /app/$SOURCE_DIR
COPY $SOURCE_DIR/run-tests.sh /usr/local/bin/run-tests.sh
COPY test/run-tests.sh /usr/local/bin/run-tests.sh
RUN chmod +x /usr/local/bin/run-tests.sh
# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds.
# Leverage a bind mount to requirements.txt to avoid having to copy them into
# into this layer.
# this layer.
RUN --mount=type=cache,target=/root/.cache/pip \
--mount=type=bind,source=${SOURCE_DIR}/requirements.txt,target=requirements.txt \
python -m pip install -r requirements.txt
--mount=type=bind,source=test/requirements.txt,target=./requirements.txt \
python -m pip install -r ./requirements.txt
# RUN --mount=type=cache,target=/root/.cache/node_modules \
# --mount=type=bind,source=package.json,target=package.json \
# npm install
WORKDIR $TESTS_DIR
ENTRYPOINT ["run-tests.sh"]
ENV TEMP_DIR=./tmp
ENTRYPOINT [ "run-tests.sh" ]
CMD [""]

10
compose.yaml
View File

@ -3,15 +3,19 @@
services:
test:
image: docs-v2-tests
container_name: docs-v2-tests
env_file:
- ./test/.env.influxdbv2
- ./test/.env.influxdbv3
volumes:
- type: bind
source: ./test/tmp
target: /app/test/tmp
source: ./test
target: /usr/src/app/test
- type: bind
source: ./data
target: /usr/src/app/test/data
build:
context: .
dockerfile: Dockerfile
args:
- SOURCE_DIR=test
- TESTS_DIR=tmp

310
content/influxdb/v2/install.md
View File

@ -48,6 +48,8 @@ For information about installing the `influx` CLI, see
We recommend using [Homebrew](https://brew.sh/) to install InfluxDB v2 on macOS:
<!--pytest.mark.skip-->
```sh
brew update
brew install influxdb
@ -61,78 +63,115 @@ For information about using the `influx` CLI, see the
### Manually download and install
To download the InfluxDB v2 binaries for macOS directly,
To download the InfluxDB v2 binary for macOS directly,
do the following:
1. **Download the InfluxDB package.**
1. Download the InfluxDB package.
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz" download>InfluxDB v2 (macOS)</a>
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz" download>InfluxDB v2 (macOS)</a>
```sh
# Download using cURL
curl -O https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz \
--output-dir ~/Downloads
```
2. **Unpackage the InfluxDB binary.**
2. Unpackage the InfluxDB binary.
Do one of the following:
- Double-click the downloaded package file in **Finder**.
- Run the following command in a macOS command prompt application such
**Terminal** or **[iTerm2](https://www.iterm2.com/)**:
- In **Finder**, double-click the downloaded package file.
- In your terminal (for example, **Terminal** or **[iTerm2](https://www.iterm2.com/)**), use `tar` to unpackage the file--for example, enter the following command to extract it into the current directory:
```sh
# Unpackage contents to the current working directory
tar zxvf ~/Downloads/influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz
```
<!--pytest-codeblocks:cont-->
3. **(Optional) Place the binary in your `$PATH`**
```sh
# Unpackage contents to the current working directory
tar zxvf ~/Downloads/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz
```
3. Optional: Place the `influxd` binary in your `$PATH`--for example, copy the binary to `/usr/local/bin`:
<!--pytest.mark.skip-->
```sh
# (Optional) Copy the influxd binary to your $PATH
sudo cp influxdb2-{{< latest-patch >}}-darwin-amd64/influxd /usr/local/bin/
sudo cp influxdb2-{{< latest-patch >}}/influxd /usr/local/bin/
```
If you do not move the `influxd` binary into your `$PATH`, prefix the executable
`./` to run it in place.
With the `influxd` binary in your `$PATH` (`/usr/local/bin`), you can enter `influxd` in your terminal to start the server.
If you choose not to move the `influxd` binary into your `$PATH`, enter the path to the binary to start the server--for example:
<!--pytest.mark.skip-->
```sh
./influxdb2-{{< latest-patch >}}/influxd
```
{{< expand-wrapper >}}
{{% expand "<span class='req'>Recommended</span> – Set appropriate directory permissions" %}}
To prevent unwanted access to data, we recommend setting the permissions on the influxdb `data-dir` to not be world readable. For server installs, it is also recommended to set a umask of 0027 to properly permission all newly created files.
To prevent unwanted access to data, set the permissions on the influxdb `data-dir` to not be world readable.
For server installs, set a umask of 0027 to properly permission all newly created files.
Example:
```shell
<!--pytest.mark.skip-->
```sh
> chmod 0750 ~/.influxdbv2
```
{{% /expand %}}
{{% expand "<span class='req'>Recommended</span> – Verify the authenticity of downloaded binary" %}}
{{% expand "<span class='req'>Recommended</span> – Verify the authenticity of the downloaded binary" %}}
For added security, use `gpg` to verify the signature of your download.
(Most operating systems include the `gpg` command by default.
If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/) for installation instructions.)
1. Download and import InfluxData's public key:
1. Download and import InfluxData's public key.
`gpg --import` outputs to stderr.
The following example shows how to import the key, redirect the output to stdout,
and then check for the expected key name:
<!-- Setup test, hide from users
```sh
gpg -q --batch --yes --delete-key D8FF8E1F7DF8B07E
```
curl -s https://repos.influxdata.com/influxdata-archive_compat.key | gpg --import -
-->
<!--pytest-codeblocks:cont-->
```sh
curl -s https://repos.influxdata.com/influxdata-archive_compat.key \
| gpg --import - 2>&1 \
| grep 'InfluxData Package Signing Key <support@influxdata.com>'
```
2. Download the signature file for the release by adding `.asc` to the download URL.
For example:
If successful, the output is similar to the following:
<!--pytest-codeblocks:expected-output-->
```
wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz.asc
gpg: key D8FF8E1F7DF8B07E: public key "InfluxData Package Signing Key <support@influxdata.com>" imported
```
3. Verify the signature with `gpg --verify`:
2. Download the signature file for the release by adding `.asc` to the download URL,
and then use `gpg` to verify the download signature--for example:
```
gpg --verify influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz.asc influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz
```sh
curl -s https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz.asc \
| gpg --verify - ~/Downloads/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz \
2>&1 | grep 'InfluxData Package Signing Key <support@influxdata.com>'
```
The output from this command should include the following:
If successful, the output is the following:
<!--pytest-codeblocks:expected-output-->
```
gpg: Good signature from "InfluxData <support@influxdata.com>" [unknown]
gpg: Good signature from "InfluxData Package Signing Key <support@influxdata.com>" [unknown]
```
{{% /expand %}}
{{< /expand-wrapper >}}
@ -153,24 +192,38 @@ the [InfluxDB HTTP API](/influxdb/v2/reference/api/).
To start InfluxDB, run the `influxd` daemon:
```bash
<!--pytest.mark.skip-->
```sh
influxd
```
{{% note %}}
#### Run InfluxDB on macOS Catalina
#### (macOS Catalina and newer) Authorize the influxd binary
macOS Catalina requires downloaded binaries to be signed by registered Apple developers.
macOS requires downloaded binaries to be signed by registered Apple developers.
Currently, when you first attempt to run `influxd`, macOS will prevent it from running.
To manually authorize the `influxd` binary:
1. Attempt to run `influxd`.
To manually authorize the `influxd` binary, follow the instructions for your macOS version to allow downloaded applications.
##### Run InfluxDB on macOS Ventura
1. Follow the preceding instructions to attempt to start `influxd`.
2. Open **System Settings** and click **Privacy & Security**.
3. Under the **Security** heading, there is a message about "influxd" being blocked, click **Allow Anyway**.
5. When prompted, enter your password to allow the setting.
6. Close **System Settings**.
7. Attempt to start `influxd`.
8. A prompt appears with the message _"macOS cannot verify the developer of "influxd"...""_.
Click **Open**.
##### Run InfluxDB on macOS Catalina
1. Attempt to start `influxd`.
2. Open **System Preferences** and click **Security & Privacy**.
3. Under the **General** tab, there is a message about `influxd` being blocked.
Click **Open Anyway**.
We are in the process of updating our build process to ensure released binaries are signed by InfluxData.
{{% /note %}}
We are in the process of updating the build process to ensure released binaries are signed by InfluxData.
{{% warn %}}
#### "too many open files" errors
@ -178,6 +231,8 @@ We are in the process of updating our build process to ensure released binaries
After running `influxd`, you might see an error in the log output like the
following:
<!--pytest.mark.skip-->
```sh
too many open files
```
@ -201,7 +256,9 @@ information about what data is collected and how it is used.
To opt-out of sending telemetry data back to InfluxData, include the
`--reporting-disabled` flag when starting `influxd`.
```bash
<!--pytest.mark.skip-->
```sh
influxd --reporting-disabled
```
{{% /note %}}
@ -236,30 +293,32 @@ For information about installing the `influx` CLI, see
```sh
# Ubuntu/Debian AMD64
wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-amd64.deb
sudo dpkg -i influxdb2-{{< latest-patch >}}-amd64.deb
curl -O https://dl.influxdata.com/influxdb/releases/influxdb2_{{< latest-patch >}}-1_amd64.deb
sudo dpkg -i influxdb2_{{< latest-patch >}}-1_amd64.deb
```
```sh
# Ubuntu/Debian ARM64
wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-arm64.deb
sudo dpkg -i influxdb2-{{< latest-patch >}}-arm64.deb
curl -O https://dl.influxdata.com/influxdb/releases/influxdb2_{{< latest-patch >}}-1_arm64.deb
sudo dpkg -i influxdb2_{{< latest-patch >}}-1_arm64.deb
```
```sh
# Red Hat/CentOS/Fedora x86-64 (x64, AMD64)
wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}.x86_64.rpm
sudo yum localinstall influxdb2-{{< latest-patch >}}.x86_64.rpm
curl -O https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-1.x86_64.rpm
sudo yum localinstall influxdb2-{{< latest-patch >}}-1.x86_64.rpm
```
```sh
# Red Hat/CentOS/Fedora AArch64 (ARMv8-A)
wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}.aarch64.rpm
sudo yum localinstall influxdb2-{{< latest-patch >}}.aarch64.rpm
curl -O https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-1.aarch64.rpm
sudo yum localinstall influxdb2-{{< latest-patch >}}-1.aarch64.rpm
```
2. Start the InfluxDB service:
<!--pytest.mark.skip-->
```sh
sudo service influxdb start
```
@ -287,6 +346,8 @@ See InfluxDB [configuration options](/influxdb/v2/reference/config-options/) for
1. Add one or more lines like the following containing arguments for `influxd` to `/etc/default/influxdb2`:
<!--pytest.mark.skip-->
```sh
ARG1="--http-bind-address :8087"
ARG2="<another argument here>"
@ -294,6 +355,8 @@ See InfluxDB [configuration options](/influxdb/v2/reference/config-options/) for
2. Edit the `/lib/systemd/system/influxdb.service` file as follows:
<!--pytest.mark.skip-->
```sh
ExecStart=/usr/bin/influxd $ARG1 $ARG2
```
@ -307,43 +370,54 @@ See InfluxDB [configuration options](/influxdb/v2/reference/config-options/) for
#### Download from your browser
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz" download >InfluxDB v2 (amd64)</a>
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-linux-arm64.tar.gz" download >InfluxDB v2 (arm)</a>
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz" download >InfluxDB v2 (amd64)</a>
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_arm64.tar.gz" download >InfluxDB v2 (arm)</a>
#### Download from the command line
```sh
# amd64
wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz
# arm
wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-linux-arm64.tar.gz
curl -O https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz
```
4. **Extract the downloaded binary.**
```sh
# arm64
curl -O https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_arm64.tar.gz
```
4. Extract the downloaded binary.
_**Note:** The following commands are examples. Adjust the filenames, paths, and utilities if necessary._
```sh
# amd64
tar xvzf path/to/influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz
# arm
tar xvzf path/to/influxdb2-{{< latest-patch >}}-linux-arm64.tar.gz
tar xvzf ./influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz
```
3. **(Optional) Place the extracted `influxd` executable binary in your system `$PATH`.**
```sh
# arm64
tar xvzf ./influxdb2-{{< latest-patch >}}_linux_arm64.tar.gz
```
3. Optional: Place the extracted `influxd` executable binary in your system `$PATH`.**
```sh
# amd64
sudo cp influxdb2-{{< latest-patch >}}-linux-amd64/influxd /usr/local/bin/
# arm
sudo cp influxdb2-{{< latest-patch >}}-linux-arm64/influxd /usr/local/bin/
sudo cp ./influxdb2-{{< latest-patch >}}/usr/bin/influxd /usr/local/bin/
```
If you do not move the `influxd` binary into your `$PATH`, prefix the executable
`./` to run it in place.
```sh
# arm64
sudo cp ./influxdb2-{{< latest-patch >}}/usr/bin/influxd /usr/local/bin/
```
If you choose to not move the `influxd` binary into your `$PATH`, enter the path to the binary to start the server--for example:
<!--pytest.mark.skip-->
```sh
./influxdb2-{{< latest-patch >}}/usr/bin/influxd
```
{{< expand-wrapper >}}
{{% expand "<span class='req'>Recommended</span> – Set appropriate directory permissions" %}}
@ -352,7 +426,9 @@ To prevent unwanted access to data, we recommend setting the permissions on the
Example:
```shell
<!--pytest.mark.skip-->
```sh
> chmod 0750 ~/.influxdbv2
```
@ -361,31 +437,50 @@ Example:
For added security, use `gpg` to verify the signature of your download.
(Most operating systems include the `gpg` command by default.
If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/) for installation instructions.)
To install `gpg`, see the [GnuPG installation instructions](https://gnupg.org/download/)).
1. Download and import InfluxData's public key:
1. Download and import InfluxData's public key.
`gpg --import` outputs to stderr.
The following example shows how to import the key, redirect the output to stdout,
and then check for the expected key name:
<!-- Setup test, hide from users
```sh
gpg -q --batch --yes --delete-key D8FF8E1F7DF8B07E
```
curl -s https://repos.influxdata.com/influxdata-archive_compat.key | gpg --import -
-->
<!--pytest-codeblocks:cont-->
```sh
curl -s https://repos.influxdata.com/influxdata-archive_compat.key \
| gpg --import - 2>&1 \
| grep 'InfluxData Package Signing Key <support@influxdata.com>'
```
2. Download the signature file for the release by adding `.asc` to the download URL.
For example:
If successful, the output is similar to the following:
<!--pytest-codeblocks:expected-output-->
```
wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz.asc
gpg: key D8FF8E1F7DF8B07E: public key "InfluxData Package Signing Key <support@influxdata.com>" imported
```
3. Verify the signature with `gpg --verify`:
2. Download the signature file for the release by adding `.asc` to the download URL,
and then use `gpg` to verify the download signature--for example:
```
gpg --verify influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz.asc influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz
```sh
curl -s https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz.asc \
| gpg --verify - influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz \
2>&1 | grep 'InfluxData Package Signing Key <support@influxdata.com>'
```
The output from this command should include the following:
If successful, the output is the following:
<!--pytest-codeblocks:expected-output-->
```
gpg: Good signature from "InfluxData <support@influxdata.com>" [unknown]
gpg: Good signature from "InfluxData Package Signing Key <support@influxdata.com>" [unknown]
```
{{% /expand %}}
{{< /expand-wrapper >}}
@ -395,7 +490,9 @@ If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/)
If InfluxDB was installed as a systemd service, systemd manages the `influxd` daemon and no further action is required.
If the binary was manually downloaded and added to the system `$PATH`, start the `influxd` daemon with the following command:
```bash
<!--pytest.mark.skip-->
```sh
influxd
```
@ -417,7 +514,9 @@ information about what data is collected and how it is used.
To opt-out of sending telemetry data back to InfluxData, include the
`--reporting-disabled` flag when starting `influxd`.
```bash
<!--pytest.mark.skip-->
```sh
influxd --reporting-disabled
```
{{% /note %}}
@ -453,13 +552,13 @@ For information about installing the `influx` CLI, see
[Install and use the influx CLI](/influxdb/v2/tools/influx-cli/).
{{% /note %}}
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-windows-amd64.zip" download >InfluxDB v2 (Windows)</a>
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-windows.zip" download >InfluxDB v2 (Windows)</a>
Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename the files if desired.
```powershell
> Expand-Archive .\influxdb2-{{< latest-patch >}}-windows-amd64.zip -DestinationPath 'C:\Program Files\InfluxData\'
> mv 'C:\Program Files\InfluxData\influxdb2-{{< latest-patch >}}-windows-amd64' 'C:\Program Files\InfluxData\influxdb'
> Expand-Archive .\influxdb2-{{< latest-patch >}}-windows.zip -DestinationPath 'C:\Program Files\InfluxData\'
> mv 'C:\Program Files\InfluxData\influxdb2-{{< latest-patch >}}' 'C:\Program Files\InfluxData\influxdb'
```
{{< expand-wrapper >}}
@ -517,7 +616,9 @@ information about what data is collected and how it is used.
To opt-out of sending telemetry data back to InfluxData, include the
`--reporting-disabled` flag when starting `influxd`.
```bash
<!--pytest.mark.skip-->
```sh
./influxd --reporting-disabled
```
{{% /note %}}
@ -533,15 +634,20 @@ Use `docker run` to download and run the InfluxDB v2 Docker image.
Expose port `8086`, which InfluxDB uses for client-server communication over
the [InfluxDB HTTP API](/influxdb/v2/reference/api/).
<!--pytest.mark.skip-->
```sh
docker run --name influxdb -p 8086:8086 influxdb:{{< latest-patch >}}
```
_To run InfluxDB in [detached mode](https://docs.docker.com/engine/reference/run/#detached-vs-foreground), include the `-d` flag in the `docker run` command._
## Persist data outside the InfluxDB container
1. Create a new directory to store your data in and navigate into the directory.
<!--pytest.mark.skip-->
```sh
mkdir path/to/influxdb-docker-data-volume && cd $_
```
@ -549,6 +655,8 @@ _To run InfluxDB in [detached mode](https://docs.docker.com/engine/reference/run
persist data from `/var/lib/influxdb2` _inside_ the container to the current working directory in
the host file system.
<!--pytest.mark.skip-->
```sh
docker run \
--name influxdb \
@ -565,6 +673,8 @@ To mount an InfluxDB configuration file and use it from within Docker:
2. Use the command below to generate the default configuration file on the host file system:
<!--pytest.mark.skip-->
```sh
docker run \
--rm influxdb:{{< latest-patch >}} \
@ -575,6 +685,8 @@ To mount an InfluxDB configuration file and use it from within Docker:
4. Start the InfluxDB container:
<!--pytest.mark.skip-->
```sh
docker run -p 8086:8086 \
-v $PWD/config.yml:/etc/influxdb2/config.yml \
@ -587,6 +699,8 @@ To mount an InfluxDB configuration file and use it from within Docker:
To use the `influx` command line interface, open a shell in the `influxdb` Docker container:
<!--pytest.mark.skip-->
```sh
docker exec -it influxdb /bin/bash
```
@ -601,6 +715,8 @@ information about what data is collected and how it is used.
To opt-out of sending telemetry data back to InfluxData, include the
`--reporting-disabled` flag when starting the InfluxDB container.
<!--pytest.mark.skip-->
```sh
docker run -p 8086:8086 influxdb:{{< latest-patch >}} --reporting-disabled
```
@ -622,16 +738,24 @@ InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) a
2. Start a local cluster:
<!--pytest.mark.skip-->
```sh
# with minikube
minikube start
```
<!--pytest.mark.skip-->
```sh
# with kind
kind create cluster
```
3. Apply the [sample InfluxDB configuration](https://github.com/influxdata/docs-v2/blob/master/static/downloads/influxdb-k8-minikube.yaml) by running:
<!--pytest.mark.skip-->
```sh
kubectl apply -f https://raw.githubusercontent.com/influxdata/docs-v2/master/static/downloads/influxdb-k8-minikube.yaml
```
@ -643,12 +767,16 @@ InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) a
4. Ensure the Pod is running:
<!--pytest.mark.skip-->
```sh
kubectl get pods -n influxdb
```
5. Ensure the Service is available:
<!--pytest.mark.skip-->
```sh
kubectl describe service -n influxdb influxdb
```
@ -657,6 +785,8 @@ InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) a
6. Forward port 8086 from inside the cluster to localhost:
<!--pytest.mark.skip-->
```sh
kubectl port-forward -n influxdb service/influxdb 8086:8086
```
@ -758,20 +888,24 @@ To avoid having to pass your InfluxDB
API token with each `influx` command, set up a configuration profile to store your credentials--for example,
enter the following code in your terminal:
<!--pytest.mark.xfail-->
{{% code-placeholders "API_TOKEN|ORG|http://localhost:8086|default|USERNAME|PASSWORD" %}}
```sh
# Set up a configuration profile
influx config create \
--config-name default \
--host-url http://localhost:8086 \
--org INFLUX_ORG \
--token INFLUX_API_TOKEN \
--org ORG \
--token API_TOKEN \
--active
```
{{% /code-placeholders %}}
Replace the following:
- **`INFLUX_ORG`**: [your organization name](/influxdb/v2/organizations/view-orgs/).
- **`INFLUX_API_TOKEN`**: [your API token](/influxdb/v2/security/tokens/view-tokens/).
- {{% code-placeholder-key %}}`ORG`{{% /code-placeholder-key %}}: [your organization name](/influxdb/v2/organizations/view-orgs/).
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: [your API token](/influxdb/v2/security/tokens/view-tokens/).
This configures a new profile named `default` and makes the profile active
so your `influx` CLI commands run against the specified InfluxDB instance.
@ -806,6 +940,8 @@ mode with an initial admin user,
[operator token](/influxdb/v2/security/tokens/#operator-token),
and bucket:
<!--pytest.mark.skip-->
```sh
influx setup \
--username USERNAME \
@ -818,6 +954,8 @@ influx setup \
The command outputs the following:
<!--pytest-codeblocks:expected-output-->
```sh
User Organization Bucket
USERNAME ORGANIZATION_NAME BUCKET_NAME
@ -847,6 +985,8 @@ or get started [collecting and writing data](/influxdb/v2/write-data).
To run setup with prompts for the required information, enter the following
command in your terminal:
<!--pytest.mark.skip-->
```sh
influx setup
```

151
content/influxdb/v2/tools/influx-cli.md
View File

@ -51,6 +51,9 @@ Do one of the following:
- [Manually download and install](#manually-download-and-install)
### Use Homebrew
<!--pytest.mark.skip-->
```sh
brew install influxdb-cli
```
@ -62,6 +65,8 @@ If you used Homebrew to install **InfluxDB {{< current-version >}}**, the `influ
formula was downloaded as a dependency and should already be installed.
If installed, `influxdb-cli` will appear in the output of the following command:
<!--pytest.mark.skip-->
```sh
brew list | grep influxdb-cli
```
@ -71,39 +76,67 @@ brew list | grep influxdb-cli
### Manually download and install
1. **Download the `influx` CLI package.**
1. Download the `influx` CLI package [from your browser](#download-from-your-browser)
or [from the command line](#download-from-the-command-line).
#### Download from your browser
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz" download>influx CLI v{{< latest-patch cli=true >}} (macOS)</a>
2. **Unpackage the downloaded package.**
#### Download from the command line
```sh
curl -O https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz \
--output-dir ~/Downloads
```
2. Unpackage the downloaded binary.
Do one of the following:
- Double-click the downloaded package file in **Finder**.
- Run the following command in a macOS command prompt application such
**Terminal** or **[iTerm2](https://www.iterm2.com/)**:
- In **Finder**, double-click the downloaded package file.
- In your terminal (for example, **Terminal** or **[iTerm2](https://www.iterm2.com/)**) use `tar` to extract the package--for example, enter the following command to extract it into `~/Downloads`:
```sh
# Unpackage contents to the current working directory
tar zxvf ~/Downloads/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz
tar zxvf ~/Downloads/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz \
--directory ~/Downloads
```
3. **(Optional) Place the binary in your `$PATH`.**
3. Optional: Place the `influx` binary in your `$PATH`--for example, copy the binary to `/usr/local/bin`:
```sh
# (Optional) Copy the influx binary to your $PATH
sudo cp ~/Downloads/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64/influx /usr/local/bin/
sudo cp ~/Downloads/influx /usr/local/bin/
```
If you do not move the `influx` binary into your `$PATH`, prefix the executable
`./` to run it in place.
With the `influx` binary in your `$PATH` (`/usr/local/bin`), you can enter `influx` in your terminal to run the CLI.
4. **(macOS Catalina and newer) Authorize the `influx` binary.**
If you do not move the `influx` binary into your `$PATH`, enter the path to the binary to run the CLI--for example:
<!--pytest.mark.xfail-->
```sh
~/Downloads/influx
```
4. (macOS Catalina and newer) Authorize the `influx` binary.
macOS requires downloaded binaries to be signed by registered Apple developers.
When you first attempt to run `influx`, macOS will prevent it from running.
When you first attempt to run `influx`, macOS prevents it from running.
To authorize the `influx` binary:
**Allow the binary on macOS Ventura**
1. Follow the preceding instructions to attempt to start `influx`.
2. Open **System Settings** and click **Privacy & Security**.
3. Under the **Security** heading, there is a message about "influxd" being blocked, click **Allow Anyway**.
5. When prompted, enter your password to allow the setting.
6. Close **System Settings**.
7. Attempt to start `influx`.
8. A prompt appears with the message _"macOS cannot verify the developer of "influx"...""_.
Click **Open**.
**Allow the binary on macOS Catalina**
1. Attempt to run an `influx` command.
2. Open **System Preferences** and click **Security & Privacy**.
3. Under the **General** tab, there is a message about `influx` being blocked.
@ -115,9 +148,7 @@ brew list | grep influxdb-cli
<!-------------------------------- BEGIN Linux -------------------------------->
{{% tab-content %}}
1. **Download the influx CLI package.**
Download the `influx` CLI package [from your browser](#download-from-your-browser)
1. Download the `influx` CLI package [from your browser](#download-from-your-browser)
or [from the command line](#download-from-the-command-line).
#### Download from your browser
@ -127,38 +158,49 @@ brew list | grep influxdb-cli
#### Download from the command line
```sh
# amd64
wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz
```sh
# amd64
wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz
```
# arm
wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz
```
```sh
# arm
wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz
```
4. **Unpackage the downloaded package.**
2. Unpackage the downloaded binary.
_**Note:** The following commands are examples. Adjust the filenames, paths, and utilities if necessary._
```sh
# amd64
tar xvzf path/to/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz
# arm
tar xvzf path/to/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz
tar xvzf ./influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz
```
3. **(Optional) Place the unpackaged `influx` executable in your system `$PATH`.**
```sh
# arm
tar xvzf ./influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz
```
3. Optional: Place the unpackaged `influx` executable in your system `$PATH`.
```sh
# amd64
sudo cp influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64/influx /usr/local/bin/
# arm
sudo cp influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64/influx /usr/local/bin/
sudo cp ./influx /usr/local/bin/
```
If you do not move the `influx` binary into your `$PATH`, prefix the executable
`./` to run it in place.
```sh
# arm
sudo cp ./influx /usr/local/bin/
```
If you do not move the `influxd` binary into your `$PATH`, enter the path to the binary to start the server--for example:
<!--pytest.mark.xfail-->
```sh
./influx
```
{{% /tab-content %}}
<!--------------------------------- END Linux --------------------------------->
@ -171,20 +213,22 @@ We recommend running `influx` CLI commands in Powershell.
Command Prompt is not fully compatible.
{{% /note %}}
1. **Download the `influx` CLI package.**
1. Download the `influx` CLI package.
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-windows-amd64.zip" download>influx CLI v{{< latest-patch cli=true >}} (Windows)</a>
2. **Expand the downloaded archive.**
2. Expand the downloaded archive.
Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename it if desired.
<!--pytest.mark.skip-->
```powershell
> Expand-Archive .\influxdb2-client-{{< latest-patch cli=true >}}-windows-amd64.zip -DestinationPath 'C:\Program Files\InfluxData\'
> mv 'C:\Program Files\InfluxData\influxdb2-client-{{< latest-patch cli=true >}}-windows-amd64' 'C:\Program Files\InfluxData\influx'
```
3. **Grant network access to the `influx` CLI.**
3. Grant network access to the `influx` CLI.
When using the `influx` CLI for the first time, **Windows Defender** displays
the following message:
@ -214,13 +258,22 @@ credentials from the active config.
Use the [`influx config create` command](/influxdb/v2/reference/cli/influx/config/create/)
to create an `influx` CLI config and set it as active:
{{% code-placeholders "API_TOKEN|ORG|http://localhost:8086|CONFIG_NAME" %}}
```sh
influx config create --config-name <config-name> \
influx config create --config-name CONFIG_NAME \
--host-url http://localhost:8086 \
--org <your-org> \
--token <your-auth-token> \
--org ORG \
--token API_TOKEN \
--active
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`CONFIG_NAME`{{% /code-placeholder-key %}}: Connection configuration name.
- {{% code-placeholder-key %}}`ORG_NAME`{{% /code-placeholder-key %}}: your InfluxDB [organization](/influxdb/v2/organizations/).
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [API token](/influxdb/v2/security/tokens/).
For more information about managing CLI configurations, see the
[`influx config` documentation](/influxdb/v2/reference/cli/influx/config/).
@ -239,16 +292,24 @@ The CLI retrieves a session cookie and stores it, unencrypted, in your
Use the `--username-password`, `-p` option to provide your username and password
using the `<username>:<password>` syntax.
If no password is provided, the CLI will prompt for a password after each
If no password is provided, the CLI prompts for a password after each
command that requires authentication.
{{% code-placeholders "API_TOKEN|ORG|http://localhost:8086|CONFIG_NAME|USERNAME|PASSWORD" %}}
```sh
influx config create \
-n config-name \
-n CONFIG_NAME \
-u http://localhost:8086 \
-p example-user:example-password \
-o example-org
-p USERNAME:PASSWORD \
-o ORG
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`CONFIG_NAME`{{% /code-placeholder-key %}}: Connection configuration name.
- {{% code-placeholder-key %}}`ORG`{{% /code-placeholder-key %}}: [your organization name](/influxdb/v2/organizations/).
- {{% code-placeholder-key %}}`USERNAME:PASSWORD`{{% /code-placeholder-key %}}: your UI username and password combination.
{{% /oss-only %}}

15
test.sh
View File

@ -30,7 +30,7 @@ rm -rf "$target"/*
# Check if the user provided a path to copy.
if [ -z "$paths" ]; then
echo "No path provided. Running tests for *.md files that have been added or modified in the current branch."
paths=$(git diff --name-only --diff-filter=AM --relative master | \
paths=$(git diff --name-only --diff-filter=AM --relative origin/master | \
grep -E '\.md$')
else
paths=$(find "$paths" -type f -name '*.md')
@ -39,5 +39,14 @@ fi
# Log the list of files to be tested and copy them to the test directory.
echo "$paths" >> "$testrun"
echo "$paths" | rsync -arv --files-from=- . "$target"
# Start a new container and run the tests.
docker compose run --no-TTY test
# Build the test image, run the tests, and then remove the container after it exits.
docker compose run --build --rm test
# To help debug test failures, run the container and pass additional flags to be used by the container's entrypoint and the test runners it executes--for example:
# docker compose run --rm test -v
# docker compose run --rm test --entrypoint /bin/bash
# If you want to examine files or run commands for debugging tests,
# start the container and use `exec` to open an interactive shell--for example:
# docker start test && docker exec -it test /bin/bash

4
test/.gitignore vendored
View File

@ -1,7 +1,9 @@
/target
/Cargo.lock
content
node_modules
tmp
.env*
.pytest_cache
.test-run.txt
tmp
parse_yaml.sh

3
test/requirements.txt
View File

@ -1,6 +1,5 @@
## Code sample dependencies
# Temporary fork for passing headers in query options.
influxdb3-python @ git+https://github.com/jstirnaman/influxdb3-python@4abd41c710e79f85333ba81258b10daff54d05b0
influxdb3-python
pandas
## Tabulate for printing pandas DataFrames.
tabulate

69
test/run-tests.sh
View File

@ -1,10 +1,44 @@
#!/bin/bash
# Function to check if an option is present in the arguments
has_option() {
local target="$1"
shift
for arg in "$@"; do
if [ "$arg" == "$target" ]; then
return 0
fi
done
return 1
}
verbose=0
# Check if "--option" is present in the CMD arguments
if has_option "-v" "$@"; then
verbose=1
echo "Using verbose mode..."
fi
if [ -z "$TEMP_DIR" ]; then
TEMP_DIR=./tmp
fi
# Parse YAML config files into dotenv files
curl -sO https://raw.githubusercontent.com/mrbaseman/parse_yaml/master/src/parse_yaml.sh
source ./parse_yaml.sh && parse_yaml ./data/products.yml > .env.products
# Load shell environment variables from .env files generated in the build (not provided at build-time.
# To provide .env files available at build-time, set them in the docker compose file).
set -a && source .env.products && set +a
cd $TEMP_DIR
for file in `find . -type f` ; do
if [ -f "$file" ]; then
echo "PROCESSING $file"
# Replace placeholder values with environment variables.
# Replaces placeholder values with environment variable references.
# Non-language-specific replacements.
sed -i 's|https:\/\/{{< influxdb/host >}}|$INFLUX_HOST|g;
' $file
@ -23,13 +57,40 @@ for file in `find . -type f` ; do
# Shell-specific replacements.
sed -i 's/API_TOKEN/$INFLUX_TOKEN/g;
s/ORG_ID/$INFLUX_ORG/g;
s/ORG/$INFLUX_ORG/g;
s/DATABASE_TOKEN/$INFLUX_TOKEN/g;
s/BUCKET_NAME/$INFLUX_DATABASE/g;
s/DATABASE_NAME/$INFLUX_DATABASE/g;
s/get-started/$INFLUX_DATABASE/g;' \
s/get-started/$INFLUX_DATABASE/g;
s/CONFIG_NAME/CONFIG_$(shuf -i 0-100 -n1)/g;' \
$file
# v2-specific replacements.
sed -i 's|https:\/\/us-west-2-1.aws.cloud2.influxdata.com|$INFLUX_HOST|g;
s|{{< latest-patch >}}|${influxdb_latest_patches_v2}|g;
s|{{< latest-patch cli=true >}}|${influxdb_latest_cli_v2}|g;' \
$file
# Skip package manager commands.
sed -i 's|sudo dpkg.*$||g;
s|sudo yum.*$||g;' \
$file
# Environment-specific replacements.
sed -i 's|sudo ||g;' \
$file
fi
cat $file
if [ $verbose -eq 1 ]; then
echo "FILE CONTENTS:"
cat $file
fi
done
pytest --codeblocks .
# Miscellaneous test setup.
# For macOS samples.
mkdir -p ~/Downloads && rm -rf ~/Downloads/*
# Clean up installed files from previous runs.
gpg -q --batch --yes --delete-key D8FF8E1F7DF8B07E > /dev/null 2>&1
# Run test commands with options provided in the CMD of the Dockerfile.
pytest --codeblocks ./content "$@"