Setting Up Production InfluxDB 2 Instance with Docker

Update: Original article has been written for InfluxDB 2.5 and now it is adapted to version 2.6 (the changelog contains a couple of new features and bug fixes).

InfluxDB is a modern and performant time series database often used to handle large amounts of timestamped data, including DevOps monitoring, application metrics, IoT sensor data, and real-time analytics.

In this article, we'll talk about the basic secure setup of the database instance using Docker containers. We'll be covering the next topics:

• Basic installation
• Configuration and data management
• Security and authorization
• Backup and restore operations

Our goal is to reveal the fundamental steps required to run a production database instance accessible via the internet.

In this article, we'll be concentrating more on management and maintenance tasks. Official InfluxDB documentation provides exceptionally clear explanations of how to read, write, explore and visualize your data.

Quick Start

InfluxDB 2 is secure out of the box and requires authentication. So let's create the first (init) super-user and respective organization and bucket. Luckily, InfxluxDB 2 docker image is being shipped with the functionality to bootstrap the system.

docker run -d -p 8086:8086 \
  --name influxdb2 \
  -v $PWD/data:/var/lib/influxdb2 \
  -v $PWD/config:/etc/influxdb2 \
  -e DOCKER_INFLUXDB_INIT_MODE=setup \
  -e DOCKER_INFLUXDB_INIT_USERNAME=root \
  -e DOCKER_INFLUXDB_INIT_PASSWORD=secret-password \
  -e DOCKER_INFLUXDB_INIT_ORG=my-init-org \
  -e DOCKER_INFLUXDB_INIT_BUCKET=my-init-bucket \
  -e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=secret-token \
  influxdb:2.6

After running the command above you'll notice a couple of new directories. These are the volumes that will contain persisted container data and configuration. It's recommended to mount volumes at both paths to avoid losing data.

tree
.
├── config
│   └── influx-configs
└── data
    ├── engine
    │   ├── data
    │   └── replicationq
    ├── influxd.bolt
    └── influxd.sqlite

5 directories, 3 files

Please, note, that the automated setup will not run if an existing boltdb is found.

At this point, you should have a ready-to-use instance. InfluxDB has an amazing UI to manage almost all the functionality. In our case, UI could be accessed using your browser by the address http://localhost:8086/. You can also use a public IP address instead of localhost if case you have it.

Use your INFLUXDB_INIT_USERNAME and INFLUXDB_INIT_PASSWORD to access UI.

Influx Client

The influx command line interface (CLI) includes commands to manage many aspects of InfluxDB, including buckets, organizations, users, tasks, etc.

In our case with Docker setup, we can just run the client using the docker exec command.

Simply type docker exec influxdb2 influx.

docker exec influxdb2 influx
NAME:
   influx - Influx Client

USAGE:
   influx [command]

HINT: If you are looking for the InfluxQL shell from 1.x, run "influx v1 shell"

COMMANDS:
   version              Print the influx CLI version
   write                Write points to InfluxDB
   bucket               Bucket management commands
   completion           Generates completion scripts
   query                Execute a Flux query
   config               Config management commands
   org, organization    Organization management commands
   delete               Delete points from InfluxDB
   user                 User management commands
   task                 Task management commands
   telegrafs            List Telegraf configuration(s). Subcommands manage Telegraf configurations.
   dashboards           List Dashboard(s).
   export               Export existing resources as a template
   secret               Secret management commands
   v1                   InfluxDB v1 management commands
   auth, authorization  Authorization management commands
   apply                Apply a template to manage resources
   stacks               List stack(s) and associated templates. Subcommands manage stacks.
   template             Summarize the provided template
   bucket-schema        Bucket schema management commands
   scripts              Scripts management commands
   ping                 Check the InfluxDB /health endpoint
   setup                Setup instance with initial user, org, bucket
   backup               Backup database
   restore              Restores a backup directory to InfluxDB
   remote               Remote connection management commands
   replication          Replication stream management commands
   server-config        Display server config
   help, h              Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help

While using Influx Client with the container you are not required to use any credentials which is obvious as you already have access to the instance. We'll talk about authorization and authentication a little bit later.

Data Management in InfluxDB

At the end of the day, InfluxDB is just a database that stores time-stamped data. To make the data usable and secure InfluxDB provides concepts of organizations, buckets, and members who can access them.

Organization

An organization is a workspace for a group of users. All dashboards, tasks, buckets, members, etc., belong to an organization.

Organizations could be created either via UI or Influx Client. Example of creating an organization via command line:

docker exec influxdb2 influx org create -n org-A
ID                      Name
f80497cd72b9a4f4        org-A

To check available organizations just use the organization list command:

docker exec influxdb2 influx organization list
ID                      Name
b904b450b99ccee2        my-init-org
f80497cd72b9a4f4        org-A

The same way you can delete and update your organizations.

Bucket

A bucket is a named location where time series data is stored. All buckets have a retention period, a duration of time that each data point persists. InfluxDB drops all points with timestamps older than the bucket’s retention period. A bucket belongs to an organization.

To create a bucket you can use UI. We'll walk through the Influx Client process.

To create a new bucket use bucket create command. Here is a minimal example:

docker exec influxdb2 influx bucket create -n bucket-A-1 -o org-A
ID                      Name            Retention       Shard group duration    Organization ID         Schema Type
694cc794c1a7050e        bucket-A-1      infinite        168h0m0s                f80497cd72b9a4f4        implicit

You can also delete, update and list your buckets in the same way.

Member

A member is a user that belongs to an organization. Users are those with access to InfluxDB. To grant a user permission to access data, add them as a member of an organization.

Additional users cannot be created in the InfluxDB UI. Influx Client will help there.

docker exec influxdb2 influx user create -n user-A-1 -p secret-password -o org-A
ID                      Name
0a4e4dd212384000        user-A-1

The same commands like list, update, and delete are also applied to the users. Additionally, you have commands to change the user password and create a recovery user.

Security, Authorization, and Authentication

To connect Influx CLI from outside the container we have to install the Influx CLI tool and provide the required authentication credentials.

InfluxDB CLI tool is available for Mac, Linux, and Windows. Please, look at the InfluxDB CLI downloads page for reference.

In our case we'll install the Mac version with the next command:

brew install influxdb-cli

Now let's create a connection config for our main administrator.

influx config create \
  --config-name root \
  --host-url http://localhost:8086 \
  --org my-init-org \
  --token secret-token \
  --active

As the result you should receive a confirmation as below:

Active  Name    URL                     Org
*       root    http://localhost:8086   my-init-org

Now, you can run your InfluxDB commands just by typing influx. Example command to show current server configuration in YAML format: influx server-config --yaml.

assets-path: ""
bolt-path: /var/lib/influxdb2/influxd.bolt
e2e-testing: false
engine-path: /var/lib/influxdb2/engine
feature-flags: null
flux-log-enabled: false
hardening-enabled: false
http-bind-address: :8086
http-idle-timeout: 180000000000
http-read-header-timeout: 10000000000
http-read-timeout: 0
http-write-timeout: 0
influxql-max-select-buckets: 0
influxql-max-select-point: 0
influxql-max-select-series: 0
instance-id: ""
log-level: info
metrics-disabled: false
nats-max-payload-bytes: 0
nats-port: 4222
no-tasks: false
pprof-disabled: false
query-concurrency: 1024
query-initial-memory-bytes: 0
query-max-memory-bytes: 0
query-memory-bytes: 0
query-queue-size: 1024
reporting-disabled: false
secret-store: bolt
session-length: 60
session-renew-disabled: false
sqlite-path: /var/lib/influxdb2/influxd.sqlite
storage-cache-max-memory-size: 1073741824
storage-cache-snapshot-memory-size: 26214400
storage-cache-snapshot-write-cold-duration: 10m0s
storage-compact-full-write-cold-duration: 4h0m0s
storage-compact-throughput-burst: 50331648
storage-max-concurrent-compactions: 0
storage-max-index-log-file-size: 1048576
storage-no-validate-field-size: false
storage-retention-check-interval: 30m0s
storage-series-file-max-concurrent-snapshot-compactions: 0
storage-series-id-set-cache-size: 0
storage-shard-precreator-advance-period: 30m0s
storage-shard-precreator-check-interval: 10m0s
storage-tsm-use-madv-willneed: false
storage-validate-keys: false
storage-wal-fsync-delay: 0s
storage-wal-max-concurrent-writes: 0
storage-wal-max-write-delay: 600000000000
storage-write-timeout: 10000000000
store: disk
testing-always-allow-setup: false
tls-cert: ""
tls-key: ""
tls-min-version: "1.2"
tls-strict-ciphers: false
tracing-type: ""
ui-disabled: false
vault-addr: ""
vault-cacert: ""
vault-capath: ""
vault-client-cert: ""
vault-client-key: ""
vault-client-timeout: 0
vault-max-retries: 0
vault-skip-verify: false
vault-tls-server-name: ""
vault-token: ""

Changing the config to connect as another user

Remember we've already created organization org-A and a member for it? Let's try to connect to the instance using the credentials of that user.

The next command will add a new config.

influx config create \
  --config-name user-a-1 \
  --host-url http://localhost:8086 \
  --org org-A
  --username-password user-A-1:secret-password \

Important to note here that this command will not switch active config. The command above just creates a new config. To switch to a new config use the influx config command.

The next command will switch Influx CLI to the newly created configuration:

influx config user-a-1

In order to have a list of all the configs you have just use the list command.

influx config list
Active  Name            URL                     Org
        user-a-1        http://localhost:8086   org-A
*       root            http://localhost:8086   my-init-org

Backup and Restore Data

There are two types of people... Hopefully, you'll be making your backups.

InfluxDB takes care of the data and moves the existing data into a temporary directory before restoring your backup. The original data in DB is being removed only in case of a successful restore operation.

Backup InfluxDB

The procedure of backup is pretty straightforward. The only requirement is root authorization token (the token created for the first user in the InfluxDB setup process). In our case, it is the token passed as DOCKER_INFLUXDB_INIT_ADMIN_TOKEN environment variable.

Influx Client configuration for an initial user (see above) just works great for making backups as the token used there. So, just run the command influx backup ./backup, and you are done.

influx backup ./backup
2022/12/23 06:51:25 INFO: Downloading metadata snapshot

In your backup directory you should see the next files:

ls -lah ./backup
total 24
drwxr-xr-x   5 danylevskyi  wheel   160B Dec 23 06:51 .
drwxrwxrwt  26 root         wheel   832B Dec 23 06:51 ..
-rw-------   1 danylevskyi  wheel   3.0K Dec 23 06:51 20221223T045125Z.bolt.gz
-rw-------   1 danylevskyi  wheel   1.7K Dec 23 06:51 20221223T045125Z.manifest
-rw-------   1 danylevskyi  wheel   3.3K Dec 23 06:51 20221223T045125Z.sqlite.gz

Also, there is an option to back up a specific bucket. InfluxDB provides a manifest file that could be used to verify the backup. The bucket should be listed there.

cat ./backup/20221223T084728Z.manifest
{
  "manifestVersion": 2,
  "kv": {
    "fileName": "20221223T084728Z.bolt.gz",
    "size": 3115,
    "compression": 1
  },
  "sql": {
    "fileName": "20221223T084728Z.sqlite.gz",
    "size": 3349,
    "compression": 1
  },
  "buckets": [
    {
      "organizationID": "65ae7d1469c4a825",
      "organizationName": "my-init-org",
      "bucketID": "d9d072450b82294c",
      "bucketName": "my-init-bucket",
      "defaultRetentionPolicy": "autogen",
      "retentionPolicies": [
        {
          "name": "autogen",
          "replicaN": 1,
          "duration": 0,
          "shardGroupDuration": 604800000000000,
          "shardGroups": [],
          "subscriptions": []
        }
      ]
    }
  ]
}

Restore InfluxDB

Let's review 3 possible options to restore your data.

1. Restore the data which is available in the backup
2. Restore the data of a specific bucket into a new bucket
3. Restore and replace all data (including key-value data such as tokens, dashboards, and users)

Restore the data which is available in the backup

To restore data available in your backup you can just run influx restore /path/to/backup/dir/.

influx restore ./backup
2022/12/26 13:47:57 INFO: Restoring bucket "5bb1580bdad5d8dc" as "my-init-bucket"
Error: failed to restore bucket "my-init-bucket": 422 Unprocessable Entity: bucket with name my-init-bucket already exists

Great! InfluxDB is taking care of us and doesn't allow overriding existing data. Let's try to delete the existing bucket and make the restore procedure again.

influx bucket delete --name my-init-bucket
ID                      Name            Retention       Shard group duration    Organization ID         Schema Type     Deleted
5bb1580bdad5d8dc        my-init-bucket  infinite        168h0m0s                6465ac29c33f7923        implicit        true

influx restore ./backup
2022/12/26 13:50:30 INFO: Restoring bucket "5bb1580bdad5d8dc" as "my-init-bucket"

As we see InfluxDB has successfully restored our original bucket.

Restore the data of a specific bucket into a new bucket

Let's imagine we have to restore a specific bucket at some point in time and also keep the existing one. We can do that with the next command:

influx restore --bucket my-init-bucket --new-bucket my-init-bucket-restored  ./backup
2022/12/26 13:56:06 INFO: Restoring bucket "5bb1580bdad5d8dc" as "my-init-bucket-restored"

Full restore: replace existing data with a backup

influx restore --full ./backup will delete existing data in your InfluxDB instance and will replace it with the data from a backup.

To illustrate how the command works let's just create a new organization and the make full restore.

influx org create -n org-B
ID                      Name
847ce1a10a9dbde1        org-B

influx org list
ID                      Name
6465ac29c33f7923        my-init-org
847ce1a10a9dbde1        org-B

influx restore --full ./backup
2022/12/26 13:59:17 INFO: Restoring KV snapshot
2022/12/26 13:59:17 INFO: Restoring SQL snapshot

influx org list
ID                      Name
6465ac29c33f7923        my-init-org

So, please, be careful! Full restore will remove all existing measurements, users, and organizations.

TLS/SSL Configuration

Your security measures will not be truly secure without setting up TLS/SSL encryption. We strongly recommend applying the configuration below.

To encrypt the communication between clients and the InfluxDB server you have to make two steps. The first one is to obtain SSL certificates. And the last one is just to spin up your container with SSL-specific arguments.

For this example, we'll place the certificates into the /srv/ssl directory. Three lines are to be added to make InfluxDB secure.

  -v /srv/ssl:/srv/ssl \
  -e INFLUXD_TLS_CERT=/srv/ssl/influx.crt \
  -e INFLUXD_TLS_KEY=/srv/ssl/influx.key \

The full command to spin up the container with an encrypted connection.

docker run -d -p 8086:8086 \
  --name influxdb2 \
  -v $PWD/data:/var/lib/influxdb2 \
  -v $PWD/config:/etc/influxdb2 \
  -v /srv/ssl:/srv/ssl \
  -e DOCKER_INFLUXDB_INIT_MODE=setup \
  -e DOCKER_INFLUXDB_INIT_USERNAME=root \
  -e DOCKER_INFLUXDB_INIT_PASSWORD=secret-password \
  -e DOCKER_INFLUXDB_INIT_ORG=my-init-org \
  -e DOCKER_INFLUXDB_INIT_BUCKET=my-init-bucket \
  -e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=secret-token \
  -e INFLUXD_TLS_CERT=/srv/ssl/influx.crt \
  -e INFLUXD_TLS_KEY=/srv/ssl/influx.key \
  influxdb:2.6

Do not forget to point your domain name to the server's IP address. After finishing the steps above you'll be able to check your SSL connection by using the next command:

curl -v https://<YOUR DOMAIN>:8086/api/v2/ping

Please note, now to work with Influx Client inside the container you have to use --host with your domain. Example of backup command inside the container:

docker exec influxdb influx backup --host=https://<DOMAIN>:8086 /backup

Final steps before going production

Here is a mini checklist for going production with InfluxDB.

• Think about data management first. Create your organizations, users, and accesses.
• Check whether your passwords are secure and stored in the proper place.
• Create a configuration on your local machine using the token to be able to make backups.
• Think about keeping the backups in a separate server.
• Set up a calendar event before the date when your SSL will be expired.
• Think about the Docker restart policy for your container.

As we see here InfluxDB 2 is a user-friendly time series database. Please, check the official documentation to get answers to your questions.