Documentation

Set up InfluxDB

This page documents an earlier version of InfluxDB. InfluxDB v2.5 is the latest stable version. View this page in the v2.5 documentation.

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

  1. If you haven’t already, download and install InfluxDB.

    Installation instructions depend on your operating system. Be sure to go through the installation and initialization process fully.

  2. Start InfluxDB.

    Run the influxd daemon to start the InfluxDB service, HTTP API, and user interface (UI).

    influxd
    

    Configure InfluxDB

    There are multiple ways to custom-configure InfluxDB. For information about what configuration options are available and how to set them, see InfluxDB configuration options.

    Once running, the InfluxDB UI is accessible at localhost:8086.

  3. (Optional) Download, install, and configure the influx CLI.

    The influx CLI provides a simple way to interact with InfluxDB from a command line. For detailed installation and setup instructions, see Use the influx CLI.

  4. (Optional) Create an All Access API token.

    During the InfluxDB initialization process, you created a user and API token that has permissions to manage everything in your InfluxDB instance. This is known as an Operator token. While you can use your Operator token to interact with InfluxDB, we recommend creating an all access token that is scoped to an organization.

    Use the InfluxDB UI, influx CLI, or InfluxDB API to create an all access token.

    1. Visit localhost:8086 in a browser to log in and access the InfluxDB UI.

    2. Navigate to Load Data > API Tokens using the left navigation bar.

    3. Click + Generate API token and select All Access API Token.

    4. Enter a description for the API token and click Save.

    5. Copy the generated token and store it for safe keeping.

    1. If you haven’t already, download, install, and configure the influx CLI.

    2. 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>
      
    3. 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:

    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.

  5. Configure authentication credentials.

    As you go through this tutorial, interactions with InfluxDB 2.4 require your InfluxDB host, organization name or ID, and your API token. There are different methods for providing these credentials depending 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 your operator token.

    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)

    Environment variables

    Command flags

    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 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=<YOUR_INFLUXDB_ORG_NAME>
    export INFLUX_ORG_ID=<YOUR_INFLUXDB_ORG_ID>
    export INFLUX_TOKEN=<YOUR_INFLUXDB_API_TOKEN>
    
  6. (Optional) Create a bucket.

    In the InfluxDB initialization process, you created a bucket. You can use that bucket or create a new 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.

    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.

    1. If you haven’t already, download, install, and configure the influx CLI.

    2. Use the influx bucket create command to create a new bucket.

      Provide the following:

      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.
    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
          }
        ]
      }'
    

Was this page helpful?

Thank you for your feedback!


Set your InfluxDB URL

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.