Set up InfluxDB

Set up InfluxDB

1 / 5

As you get started with this tutorial, do the following to make sure everything you need is in place.

Run the initial setup process
Create an All Access API token
Configure authentication credentials
Create a bucket

Run the initial setup process.

After you install and start InfluxDB, run the initial setup process to create the following:
- An organization with the name you provide.
- A bucket with the name you provide.
- An admin authorization with the following properties:
  - The username and password that you provide.
  - An API Operator token.
  - Read-write permissions for all resources in the InfluxDB instance.
You can use the InfluxDB UI, the influx CLI, or the HTTP API to run the setup process.
- To run an interactive setup that prompts you for the required information, use the InfluxDB user interface (UI) or the influx command line interface (CLI).
- To automate the setup–for example, with a script that you write– use the influx command line interface (CLI) or the /api/v2/setup InfluxDB API endpoint.
Automated setup with Docker
If you installed InfluxDB using Docker with initial setup options, then you’ve already completed the setup process.

Set up with the UI Set up with the CLI Set up with the API
1. With InfluxDB running, visit http://localhost:8086.
2. Click Get Started
Set up your initial user
1. Enter a Username for your initial user.
2. Enter a Password and Confirm Password for your user.
3. Enter your initial Organization Name.
4. Enter your initial Bucket Name.
5. Click Continue.
6. Copy the provided operator API token and store it for safe keeping.
We recommend using a password manager or a secret store to securely store sensitive tokens.

Your InfluxDB instance is now initialized.
1. Download and install the influx CLI, which provides a simple way to interact with InfluxDB from a command line. For detailed installation and setup instructions, see Use the influx CLI.
2. Use the influx setup CLI command to initialize your InfluxDB instance–choose one of the following:
  - Set up with prompts. To setup interactively, enter the following command:
```
influx setup
```
    The command walks you through the initial setup process by prompting for a username, password, organization, bucket, and retention period.
  - Set up non-interactively. To run setup non-interactively (for example, in your automation scripts), pass command line flags for the initialization values, and pass the -f, --force flag to bypass the final confirmation prompt–for example, enter the following command:
```
influx setup \
  --username USERNAME \
  --password PASSWORD \
  --token TOKEN \
  --org ORG_NAME \
  --bucket BUCKET_NAME \
  --force
```
    Replace the following:
    - USERNAME: A name for your initial admin user
    - PASSWORD: A password for your initial admin user
    - TOKEN: A string value to set for the operator token. If you don’t include this flag, InfluxDB generates a token for you and stores it in an influx CLI connection configuration.
    - ORG_NAME: A name for your initial organization
    - BUCKET_NAME: A name for your initial bucket
  InfluxDB is initialized with an Operator token, user, organization, and bucket. The output is similar to the following:
```
User        Organization         Bucket
USERNAME    ORGANIZATION_NAME    BUCKET_NAME
```
  InfluxDB stores these values in a default connection configuration that provides your InfluxDB URL, organization, and API token to influx CLI commands. For information about connection configurations, see influx config.
Send a request to the following HTTP API endpoint:
```
POST http://localhost:8086/api/v2/setup
```
The POST /api/v2/setup API endpoint doesn’t require authentication

In the request body, specify values for the initial username, password, organization, bucket, and an optional Operator token–for example:
```
curl http://localhost:8090/api/v2/setup \
  --data '{
            "username": "USERNAME",
            "password": "PASSWORD",
            "token": "TOKEN",
            "bucket": "BUCKET_NAME",
            "org": "ORG_NAME"
        }'
```
Replace the following:
- USERNAME: A name for your initial admin user
- PASSWORD: A password for your initial admin user
- ORG_NAME: A name for your initial organization
- BUCKET_NAME: A name for your initial bucket
- TOKEN: A string value to set for the operator token. If you don’t include this flag, InfluxDB generates a token for you.
The response body contains the created resources, including the Operator token and its list of permissions.

We recommend using a password manager or a secret store to securely store sensitive tokens.

For more options and details, see the POST /api/v2/setup API endpoint documentation.

Recommended: Create an All Access API token.

During the InfluxDB initial set up process, you created an admin user and Operator token that have permissions to manage everything in your InfluxDB instance.

While you can use your Operator token to interact with InfluxDB, we recommend creating an All Access token that is scoped to an organization, and then using this token to manage InfluxDB. Use the InfluxDB UI, influx CLI, or InfluxDB API to create an All Access token.

InfluxDB UI influx CLI InfluxDB API

Visit localhost:8086 in a browser to log in and access the InfluxDB UI.
Navigate to Load Data > API Tokens using the left navigation bar.
Click + Generate API token and select All Access API Token.
Enter a description for the API token and click Save.
Copy the generated token and store it for safe keeping.
If you haven’t already, download, install, and configure the influx CLI.
Use the influx auth create command to create an All Access token.

Provide the following:
- --all-access flag
- --host flag with your InfluxDB host URL
- -o, --org or --org-id flags with your InfluxDB organization name or ID
- -t, --token flag with your Operator token
```
influx auth create \
  --all-access \
  --host http://localhost:8086 \
  --org <YOUR_INFLUXDB_ORG_NAME> \
  --token <YOUR_INFLUXDB_OPERATOR_TOKEN>
```
Copy the generated token and store it for safe keeping.

Send a request to the InfluxDB API /api/v2/authorizations endpoint using the POST request method.

POST http://localhost:8086/api/v2/authorizations

Include the following with your request:

Headers:
- Authorization: Token <INFLUX_OPERATOR_TOKEN>
- Content-Type: application/json
Request body: JSON body with the following properties:
- status: "active"
- description: API token description
- orgID: InfluxDB organization ID
- permissions: Array of objects where each object represents permissions for an InfluxDB resource type or a specific resource. Each permission contains the following properties:
  - action: “read” or “write”
  - resource: JSON object that represents the InfluxDB resource to grant permission to. Each resource contains at least the following properties:
    - orgID: InfluxDB organization ID
    - type: Resource type. For information about what InfluxDB resource types exist, use the /api/v2/resources endpoint.

The following example uses cURL and the InfluxDB API to generate an All Access token:

export INFLUX_HOST=http://localhost:8086
export INFLUX_ORG_ID=<YOUR_INFLUXDB_ORG_ID>
export INFLUX_TOKEN=<YOUR_INFLUXDB_OPERATOR_TOKEN>
curl --request POST \
"$INFLUX_HOST/api/v2/authorizations" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --header "Content-Type: text/plain; charset=utf-8" \
  --data '{
    "status": "active",
    "description": "All access token for get started tutorial",
    "orgID": "'"$INFLUX_ORG_ID"'",
    "permissions": [
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "authorizations"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "authorizations"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "buckets"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "buckets"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "dashboards"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "dashboards"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "orgs"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "orgs"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "sources"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "sources"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "tasks"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "tasks"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "telegrafs"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "telegrafs"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "users"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "users"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "variables"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "variables"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "scrapers"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "scrapers"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "secrets"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "secrets"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "labels"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "labels"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "views"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "views"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "documents"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "documents"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notificationRules"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notificationRules"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notificationEndpoints"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notificationEndpoints"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "checks"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "checks"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "dbrp"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "dbrp"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notebooks"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notebooks"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "annotations"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "annotations"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "remotes"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "remotes"}},
      {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "replications"}},
      {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "replications"}}
    ]
  }
'

The response body contains a JSON object with the following properties:

id: API Token ID
token: API Token (Important)
status: Token status
description: Token description
orgID: InfluxDB organization ID the token is associated with
org: InfluxDB organization name the token is associated with
userID: User ID the token is associated with
user: Username the token is associated with
permissions: List of permissions for organization resources

Copy the generated token and store it for safe keeping.

We recommend using a password manager or a secret store to securely store sensitive tokens.

Configure authentication credentials.

As you go through this tutorial, interactions with InfluxDB 2.7 require your InfluxDB host, organization name or ID, and your API token. How you provide credentials depends on which client you use to interact with InfluxDB.

When configuring your token, if you created an All Access token, use that token to interact with InfluxDB. Otherwise, use the Operator token that you created during the setup process.

InfluxDB UI influx CLI InfluxDB API

When managing InfluxDB through the InfluxDB UI, authentication credentials are provided automatically using credentials associated with the user you log in with.

There are three ways to provided authentication credentials to the influx CLI:

CLI connection configurations (Recommended)

The influx CLI lets you specify connection configuration presets that let you store and quickly switch between multiple sets of InfluxDB connection credentials. A connection configuration stores your credentials to avoid having to pass your InfluxDB API token with each influx command.

If you set up InfluxDB using the CLI, it creates a default connection configuration for you.

Use the influx config create command to manually create a new CLI connection configuration for the All Access token you created in the preceding step. Include the following flags:
```
influx config create \
  --config-name get-started \
  --host-url http://localhost:8086 \
  --org ORG_NAME \
  --token API_TOKEN
```
Replace the following:
- get-started: Connection configuration name. Examples in this tutorial use get-started.
- http://localhost:8086: InfluxDB host URL.
- ORG: your organization name.
- API_TOKEN: your API token.
For more information about influx CLI connection configurations, see Install and use the influx CLI.

Environment variables

The influx CLI checks for specific environment variables and, if present, uses those environment variables to populate authentication credentials. Set the following environment variables in your command line session:
- INFLUX_HOST: InfluxDB host URL.
- INFLUX_ORG: InfluxDB organization name.
- INFLUX_ORG_ID: InfluxDB organization ID.
- INFLUX_TOKEN: InfluxDB API token.
```
export INFLUX_HOST=localhost:8086
export INFLUX_ORG=<ORG_NAME>
export INFLUX_ORG_ID=<ORG_ID>
export INFLUX_TOKEN=<API_TOKEN>
```
Replace the following:
- <ORG_NAME>: The name of your organization
- <ORG_ID>: Your organization ID
- <API_TOKEN>: Your All Access token or operator token
Command line flags

Use the following influx CLI flags to provide required credentials to commands:
- --host: InfluxDB host URL.
- -o, --org or --org-id: InfluxDB organization name or ID.
- -t, --token: InfluxDB API token.
All influx CLI examples in this getting started tutorial assume your InfluxDB host, organization, and token are provided by either the active influx CLI configuration or by environment variables.

When using the InfluxDB API, provide the required connection credentials in the following ways:
- InfluxDB host: The domain and port to send HTTP(S) requests to.
- InfluxDB API Token: Include an Authorization header that uses either the Bearer or Token scheme and your InfluxDB API token–for example:
```
Authorization: Bearer 0xxx0o0XxXxx00Xxxx000xXXxoo0==
```
- InfluxDB organization name or ID: Depending on the API endpoint used, pass this as part of the URL path, query string, or in the request body.
All API examples in this tutorial use cURL from a command line. To provide all the necessary credentials to the example cURL commands, set the following environment variables in your command line session.
```
export INFLUX_HOST=http://localhost:8086
export INFLUX_ORG=<ORG_NAME>
export INFLUX_ORG_ID=<ORG_ID>
export INFLUX_TOKEN=<API_TOKEN>
```
Replace the following:
- <ORG_NAME>: The name of your organization
- <ORG_ID>: Your organization ID
- <API_TOKEN>: Your All Access token or Operator token
Optional: Create a bucket.

In the initial setup process, you created a bucket. You can use that bucket or create one specifically for this getting started tutorial. All examples in this tutorial assume a bucket named get-started.

Use the InfluxDB UI, influx CLI, or InfluxDB API to create a new bucket.

InfluxDB UI influx CLI InfluxDB API
1. Visit localhost:8086 in a browser to log in and access the InfluxDB UI.
2. Navigate to Load Data > Buckets using the left navigation bar.
3. Click + Create bucket.
4. Provide a bucket name (get-started) and select Never to create a bucket with an infinite retention period.
5. Click Create.
6. If you haven’t already, download, install, and configure the influx CLI.
7. Use the influx bucket create command to create a bucket.
  
  Provide the following:
  - -n, --name flag with the bucket name.
  - Connection and authentication credentials
```
influx bucket create --name get-started
```
To create a bucket using the InfluxDB HTTP API, send a request to the InfluxDB API /api/v2/buckets endpoint using the POST request method.
```
POST http://localhost:8086/api/v2/buckets
```
Include the following with your request:
- Headers:
  - Authorization: Token INFLUX_TOKEN
  - Content-Type: application/json
- Request body: JSON object with the following properties:
  - org: InfluxDB organization name
  - name: Bucket name
  - retentionRules: List of retention rule objects that define the bucket’s retention period. Each retention rule object has the following properties:
    - type: "expire"
    - everySeconds: Retention period duration in seconds. 0 indicates the retention period is infinite.
The following example shows how to use cURL and the InfluxDB API to create a bucket:
```
export INFLUX_HOST=http://localhost:8086
export INFLUX_ORG_ID=<YOUR_INFLUXDB_ORG_ID>
export INFLUX_TOKEN=<YOUR_INFLUXDB_API_TOKEN>
curl --request POST \
"$INFLUX_HOST/api/v2/buckets" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "orgID": "'"$INFLUX_ORG_ID"'",
    "name": "get-started",
    "retentionRules": [
      {
        "type": "expire",
        "everySeconds": 0
      }
    ]
  }'
```

Get started Write data

Set up InfluxDB

Set up InfluxDB

Automated setup with Docker

Set up your initial user

Related