Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 39 ยท Getting Started

Installing and Running InfluxDB

Install and start InfluxDB 2.x and InfluxDB 3 Core with Docker or packages, set up the first user and token, and check that the server is healthy.

InfluxDB is a single server program. You can run it from a Docker image, a package for your operating system or a plain binary. This lesson shows the common ways to start InfluxDB 2.x and InfluxDB 3 Core on your own machine, how to complete first-time setup and how to check that the server is alive.

Every command in this lesson is read-only here: the site cannot start a database server. Run them in your own terminal. Flags and image tags change between releases, so when a command fails, run it with --help and read the official release notes for your version. The runnable blocks are JavaScript stand-ins that build the URLs and parse the health answers you will see.

Before you start

  • A 64-bit machine with a few gigabytes of free disk space for tests.
  • Docker, if you want the easiest route. Packages and binaries work too.
  • Free ports: 8086 is the classic InfluxDB 1.x and 2.x port; InfluxDB 3 Core listens on 8181 by default.
  • A terminal where you can run curl.

InfluxDB 2.x with Docker

Terminal
docker run -d --name influxdb2 -p 8086:8086 \
  -v influxdb2-data:/var/lib/influxdb2 \
  -v influxdb2-config:/etc/influxdb2 \
  influxdb:2

The two named volumes keep your data and configuration when the container is replaced. Open http://localhost:8086 in a browser. The first screen is the onboarding form: choose a user name and password, an organization name and the name of your first bucket. You can also skip the browser and do it in the terminal:

Terminal
docker exec influxdb2 influx setup \
  --username admin --password 'change-me-please' \
  --org my-org --bucket my-bucket --retention 0 --force

--retention 0 means "keep data forever". Setup prints an operator token. Treat it like a root password: it can do anything. Later you will create narrower tokens (Buckets, Organizations and Tokens).

InfluxDB 3 Core with Docker

InfluxDB 3 Core runs as one process called influxdb3. It needs to know where to keep data (a local folder or an object store) and a node name:

Terminal
docker run -d --name influxdb3 -p 8181:8181 \
  -v influxdb3-data:/var/lib/influxdb3 \
  influxdb:3-core influxdb3 serve \
  --node-id node0 \
  --object-store file \
  --data-dir /var/lib/influxdb3

Newer releases may ask for extra options such as a cluster ID; influxdb3 serve --help lists exactly what your version needs. When authentication is enabled (the default), create the first admin token before anything else:

Terminal
docker exec influxdb3 influxdb3 create token --admin

The token is shown once. Copy it into a password manager or an environment variable such as INFLUXDB3_AUTH_TOKEN; the server cannot show it again.

Installing without Docker

Packages and binaries are available for Linux, macOS and Windows (2.x also has a Windows service build; 3.x ships a shell installer for Linux and macOS). The pattern is the same everywhere: download, start the server, finish setup.

Terminal
# Linux with a package manager (2.x), after adding the official repository
sudo apt-get install influxdb2 influxdb2-cli
sudo systemctl enable --now influxdb

# 3.x Core with the vendor's install script
curl -O https://www.influxdata.com/d/install_influxdb3.sh
sh install_influxdb3.sh
influxdb3 serve --node-id node0 --object-store file --data-dir ~/.influxdb3

Always download from the official site and, when checksums or signatures are offered, verify them.

Checking that it works

Both generations answer health requests over HTTP:

Terminal
curl -s http://localhost:8086/health      # 2.x
curl -s http://localhost:8181/health      # 3.x

For 2.x the answer is a small JSON document with a status of pass and the version. The next block mimics reading it and builds the URLs you will use throughout the course. It is a JavaScript stand-in; the sample answer is typed in, not fetched.

JS Reading a health answer (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Configuration basics

InfluxDB reads settings from command-line flags, environment variables and config files, in that order of priority.

  • 2.x: influxd --http-bind-address=:8086, environment variables like INFLUXD_HTTP_BIND_ADDRESS, or config.toml / config.yml in the working or /etc/influxdb2 folder.
  • 3.x: flags such as --http-bind 0.0.0.0:8181, with environment variables like INFLUXDB3_HTTP_BIND_ADDR (see influxdb3 serve --help for the exact names in your version).

Three settings matter on every machine:

  1. Where data lives. Put it on a disk with room to grow, and back it up (the retention chapter of this course explains why it will grow).
  2. Who can reach it. Keep the port off the public internet unless you put TLS and authentication in front.
  3. Which token you use. Never reuse the operator token inside applications.

Troubleshooting

Symptom Likely cause
connection refused Server not running, or wrong port
401 Unauthorized Missing or wrong token; check the Authorization header
port is already allocated Another program uses 8086 or 8181; map a different host port, e.g. -p 8087:8086
Setup form does not appear (2.x) Already onboarded; sign in instead
Data vanished after a restart Container started without a volume

A quick sanity script

This stand-in checks a list of common mistakes in a config before you start. It is again only JavaScript, but it shows the kind of preflight reasoning that saves time.

JS Preflight checklist (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which port does InfluxDB 2.x listen on by default?

    8086 is the classic port for 1.x and 2.x; InfluxDB 3 Core uses 8181.
  2. 2. Why mount a Docker volume for the data directory?

    Without a volume the data lives in the container's writable layer and is lost with it.
  3. 3. When is the 3.x admin token displayed?

    Tokens are stored hashed, so copy the value when it is created.
  4. 4. Which request checks that a 2.x server is ready?

    GET /health returns status pass and the version when the server is ready.

Summary

  • InfluxDB is one server; run it from Docker, a package or a binary.
  • 2.x listens on 8086 with onboarding (user, org, bucket); 3 Core uses influxdb3 serve on 8181.
  • Create an admin token once, store it safely and use narrower tokens for applications.
  • GET /health tells you whether the server is up.
  • Use volumes for data, TLS for public access and --help for flags that changed in your version.

Next: The InfluxDB CLI and UI Tour