Self-hosted InfluxDB, with your time-series data on a server of your own

Is Core the right InfluxDB for your job?

Yes, if you collect recent readings and look at them quickly; long history is what paid Enterprise adds. Check these documented limits first.

• At most 5 databases per server.
• Each query may open 432 Parquet files (query-file-limit). With the default 10-minute files a query covers no more than roughly 72 hours, and sometimes less; you can raise it, at a cost in memory and speed.
• A database's retention period is fixed when you create it.
• One server only, with no standby copy or read replicas.
• Its documented tokens are admin tokens with every permission; give each app its own.

The server that fits

Core writes Parquet files and a write-ahead log to local disk, so a quick drive pays off. Hence an NVMe server, a complete HPE Moonshot cartridge whose NVMe SSD nobody else touches, one drive or a software RAID 1 pair, with a 1 Gbps port nobody meters.

InfluxData gives no minimum machine, only sample setups; the job sizes and cartridge pairings are ours.

To apply a row, put num-io-threads=6 and then exec-mem-pool-size="45gb" into /etc/influxdb3/influxdb3-core.conf and restart Core. Mirror two drives (each 240 GB up to 3.84 TB) and keep backups, since a mirror copies mistakes too.

Racked machines are yours about 30 minutes after your order is approved; a build you configure takes 4 to 24 hours when we hold the parts, longer when one has to be bought in. The NVMe cartridges come with an HPE iLO console in your browser, with virtual media, so you can boot an installer of your own.

Up and running on Ubuntu 24.04

Until an admin token exists, anyone who reaches port 8181 can create one, and Core answers on all addresses by default; the setup guide warns they could then run code on your server. So you create the token yourself, offline, and keep Core on 127.0.0.1.

Firewall before anything else. The OpenSSH profile covers port 22 only, so if your SSH runs on another port, swap OpenSSH for that port (say 2222/tcp) before running sudo apt update && sudo apt install ufw -y && sudo sed -i /etc/default/ufw -e '/^IPV6=/c IPV6=yes' && sudo ufw limit OpenSSH && sudo ufw --force enable. Then paste this block, which ends with ok or STOP.

cd /tmp && curl -sLO https://repos.influxdata.com/influxdata-archive.key \
&& gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 \
| grep -q '^fpr::*24C975CBA61A024EE1B631787C3D57159FC2F927:$' \
&& gpg --dearmor < influxdata-archive.key | sudo tee /usr/share/keyrings/influxdata-archive.gpg >/dev/null \
&& echo 'deb [signed-by=/usr/share/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \
| sudo tee /etc/apt/sources.list.d/influxdata.list \
&& sudo apt-get update && sudo apt-get install -y influxdb3-core \
|| echo "STOP - key check or apt install did not finish"
C=/etc/influxdb3/influxdb3-core.conf; T=/etc/influxdb3/admin-token.json
sudo test -f "$C" && sudo test ! -e "$T" && ! sudo grep -q '^http-bind' "$C" \
&& sudo influxdb3 create token --admin --offline --output-file "$T" \
&& sudo chown influxdb3:influxdb3 "$T" && sudo chmod 750 /etc/influxdb3 \
&& printf '%s\n' 'http-bind="127.0.0.1:8181"' "admin-token-file=\"$T\"" 'disable-telemetry-upload=true' \
| sudo tee -a "$C" >/dev/null && sudo systemctl enable --now influxdb3-core \
&& timeout 60 sh -c 'until curl -so /dev/null http://127.0.0.1:8181/health; do sleep 2; done' \
&& export INFLUXDB3_AUTH_TOKEN="$(sudo python3 -c 'import json,sys;print(json.load(open(sys.argv[1]))["token"])' "$T")" \
&& influxdb3 show databases && ss -ltn | grep -q '127.0.0.1:8181 ' && echo "ok - up on 127.0.0.1:8181" \
|| echo "STOP - read the recovery note under this block"

1. Up to the first STOP line it is InfluxData's DEB install with its fingerprint check, made into a single chain, with -y, cd /tmp, a < feeding in the key and a closing STOP line as our additions.
2. The rest is ours. Called with no --name, the offline command writes the operator token _admin, no expiry, to a mode-600 file (per token.rs); we give it to the influxdb3 user, keep it 600 as the token guide wants, and close /etc/influxdb3 to 750.
3. Three lines go on the end of the package's config, for loopback only, the token file and no telemetry upload.
4. The token lives in INFLUXDB3_AUTH_TOKEN for this terminal only; a new one needs export INFLUXDB3_AUTH_TOKEN=$(sudo grep -o 'apiv3_[^"]*' /etc/influxdb3/admin-token.json) (tokens start with apiv3_, per influxdb3_catalog/src/catalog.rs).

Saw STOP? Work through these in order.

• From the key check or apt, paste the whole block again.
• Otherwise ask whether Core ever ran with sudo find /var/lib/influxdb3/data -maxdepth 1 -name primary-node | grep -q . && echo started || echo never. If you see started, the server holds that token, so keep the file and look at sudo journalctl -u influxdb3-core -b.
• If it prints never, check for the three lines with sudo tail -3 /etc/influxdb3/influxdb3-core.conf. Take out just those with sudo sed -i '/^disable-telemetry-upload=true$/d;/^admin-token-file=/d;/^http-bind="127.0.0.1:8181"$/d' /etc/influxdb3/influxdb3-core.conf, run sudo rm /etc/influxdb3/admin-token.json, and paste the block again from the line starting C=.

Getting your metrics in

Telegraf 1.38 or newer has the influxdb_v3 output, and the repository you added carries it. Work in the terminal that has your token.

1. Install the agent with sudo apt install telegraf.
2. Make a database, choosing its retention for good, with influxdb3 create database --retention-period 90d metrics.
3. Create the agent's token with influxdb3 create token --admin --name collector (shown once), then read -rs TOKEN and paste it, so it stays out of your history.
4. Store it in the private file Telegraf's service loads, with `case "$TOKEN" in apiv3_*) ! sudo grep -qs '^INFLUX_TOKEN=' /etc/default/telegraf && sudo sh -c 'umask 077; touch /etc/default/telegraf && chmod go= /etc/default/telegraf' && echo "INFLUX_TOKEN=$TOKEN" | sudo sh -c 'cat >> /etc/default/telegraf' && echo "ok - token stored" || echo "STOP - INFLUX_TOKEN is already in the file, or writing it did not work";; *) echo "STOP - TOKEN does not hold an apiv3_ value";; esac`.
5. Point Telegraf at Core with printf '[[outputs.influxdb_v3]]\n database = "metrics"\n token = "${INFLUX_TOKEN}"\n urls = ["http://127.0.0.1:8181"]' | sudo tee /etc/telegraf/telegraf.d/output-influxdb3.conf and restart it (sudo systemctl restart telegraf).
6. After a minute, influxdb3 query --database metrics "SHOW TABLES" should list what arrived.

Sending from other machines needs TLS. Copy the certificate and key in with sudo install -o root -g influxdb3 -m 640 fullchain.pem privkey.pem /etc/influxdb3/ and add the two keys, only if no tls line is there yet, with sudo grep -qs '^tls-' /etc/influxdb3/influxdb3-core.conf || printf 'tls-cert="/etc/influxdb3/fullchain.pem"\ntls-key="/etc/influxdb3/privkey.pem"\n' | sudo sh -c 'cat >> /etc/influxdb3/influxdb3-core.conf'. Change the existing bind line (a second one makes the file invalid TOML) with sudo sed -i /etc/influxdb3/influxdb3-core.conf -e '/^http-bind=/c http-bind="0.0.0.0:8181"', and restart Core. Whenever the certificate renews, run that install line again and restart, and keep the name pointing at this server. ufw still decides who gets in, so open 8181 to those senders alone, e.g. sudo ufw allow proto tcp from 198.51.100.7 to any port 8181. Local tools then need https and the name on the certificate, so set Telegraf's urls to ["https://influx.example.net:8181"], and for the CLI, export INFLUXDB3_HOST_URL=https://influx.example.net:8181. MQTT sensors usually go through a broker first, as our MQTT broker guide shows.

Keeping a copy you can restore

Core has no backup command. InfluxData's guide copies the parts of the node's folder in a set order at quiet times, since a copy taken while busy may be inconsistent. This script stops Core while it packs the folder, so the order no longer matters (writes are turned away meanwhile, so run it at night). It skips table-snapshots, which Core rebuilds, adds /etc/influxdb3 (your token, so treat archives as secrets) and any plugins folder, checks the result, and only then clears archives past 14 days, our number. The agent's own token stays outside the archive, so after a move Telegraf gets a new one.

# /usr/local/sbin/backup-influxdb3.sh, run by root with bash
umask 077
D=/var/lib/influxdb3/data; N=primary-node; B=/var/backups/influxdb3
A="$B/influxdb3-$(date +%F-%H%M%S).tar.gz"; X=
install -d -m 700 "$B" && test -d "$D/$N" || { echo "STOP - $D/$N not found"; exit 1; }
test -d /var/lib/influxdb3/plugins && X="-C /var/lib/influxdb3 plugins"
trap 'systemctl start influxdb3-core' EXIT
systemctl stop influxdb3-core \
&& tar -czf "$A.part" --exclude="$N/table-snapshots" -C "$D" "$N" -C / etc/influxdb3 $X \
&& systemctl start influxdb3-core && L=$(tar -tzf "$A.part") \
&& grep -q "^$N/catalog" <<<"$L" && grep -qx 'etc/influxdb3/admin-token.json' <<<"$L" \
&& mv "$A.part" "$A" && echo "ok $A" \
|| { rm -f "$A.part"; echo "STOP - no new archive was kept, read the lines above"; exit 1; }
find "$B" \( -name 'influxdb3-*.tar.gz' -o -name 'run-*.log' \) -mtime +14 -delete \
|| echo "prune did not finish; the new archive $A was kept"

Save that as /usr/local/sbin/backup-influxdb3.sh. Make its folder with sudo mkdir -m 700 /var/backups/influxdb3, run sudo bash /usr/local/sbin/backup-influxdb3.sh once and look for ok, then add a nightly run with echo '40 2 * * * root bash /usr/local/sbin/backup-influxdb3.sh > /var/backups/influxdb3/run-$(date +\%Y\%m\%d).log 2>&1' | sudo sh -c 'cat > /etc/cron.d/backup-influxdb3'. You manage the server, so also keep copies elsewhere, pulled by rsync -a without --delete.

To bring one back, write the archive's name into A and paste. Nothing stops until the checks pass, and current data is moved aside, not erased.

D=/var/lib/influxdb3/data; N=primary-node; P="$D/$N.previous"
A=/var/backups/influxdb3/influxdb3-YYYY-MM-DD-HHMMSS.tar.gz
sudo test -f "$A" && L=$(sudo tar -tzf "$A") && grep -q "^$N/catalog" <<<"$L" \
&& sudo test ! -e "$P" && sudo test -d "$D/$N" \
&& sudo systemctl stop influxdb3-core && sudo mv "$D/$N" "$P" \
&& sudo tar -C "$D" -xzf "$A" "$N" && sudo chown -R influxdb3:influxdb3 "$D/$N" \
&& sudo systemctl start influxdb3-core && sleep 15 && systemctl is-active --quiet influxdb3-core \
&& echo "ok - restored; the data from before sits in $P" \
|| echo "STOP - archive missing or unreadable or without a catalog, a leftover $P, no live folder, Core would not stop, an extract error, or files back but Core did not start (sudo journalctl -u influxdb3-core -n 50); if $P exists, roll back as below"

Core will not start, or the data is wrong? Put the old folder back with `W=/var/lib/influxdb3/data; L=$W/primary-node; sudo test -d "$L.previous" && sudo test ! -e "$L.failed" && sudo systemctl stop influxdb3-core && { if sudo test -e "$L"; then sudo mv "$L" "$L.failed"; fi; } && sudo mv "$L.previous" "$L" && sudo systemctl restart influxdb3-core && sleep 20 && systemctl is-active influxdb3-core && echo "ok - the earlier data is live again" || echo "STOP - nothing to go back to, primary-node.failed is in the way, or the service stayed down". When everything looks right, clear the spare copies with sudo rm -rf /var/lib/influxdb3/data/primary-node.previous /var/lib/influxdb3/data/primary-node.failed`.

Moving to a fresh server? Do these in order.

1. Set up the firewall and paste only the install block's first part, up to its first STOP line; the archive carries your token.
2. Make the folder with sudo mkdir -m 700 /var/backups/influxdb3, put the archive in it, and point A at its full path.
3. Unpack the config and start Core once with `W=/var/lib/influxdb3/data; sudo tar -xzf "$A" -C / etc/influxdb3 && sudo systemctl start influxdb3-core && timeout 90 bash -c "while ! sudo test -d $W/primary-node; do sleep 3; done" && echo "ok - Core is up, restore next" || echo "STOP - the config did not unpack or Core did not come up; check sudo journalctl -u influxdb3-core -b"`.
4. Restore any plugins with `if sudo tar -tf "$A" | grep -q '^plugins/'; then sudo tar -xzf "$A" -C /var/lib/influxdb3 plugins && sudo chown -R influxdb3: /var/lib/influxdb3/plugins && printf 'plugins back, ok\n' || echo "STOP - could not unpack plugins"; else echo "this archive has no plugins"; fi`.
5. Run the restore block with the same A.
6. Load your admin token into this terminal with export INFLUXDB3_AUTH_TOKEN=$(sudo grep -o 'apiv3_[^"]*' /etc/influxdb3/admin-token.json). The restored catalog still trusts the old collector token, so revoke it, influxdb3 delete token --token-name collector -y (the -y answers the confirmation, per delete.rs in the source), then give Telegraf a fresh token the same way as before.

Updating without getting stuck

3.9 cannot read a catalog 3.10 wrote, and 3.11 cannot load one 3.12 has used; the upgrade guide names a catalog backup as the only route back. So every update goes like this.

1. Run the backup script for a new archive and wait for ok.
2. Check the offered version with apt-cache policy influxdb3-core and read its release notes.
3. Update with sudo apt update && sudo apt install --only-upgrade influxdb3-core, which restarts a running service.
4. Confirm with influxdb3 show databases and influxdb3 --version.

To go back, first sudo systemctl stop influxdb3-core, or the package would restart it on the newer catalog. Then install the old version, sudo apt install influxdb3-core=VERSION --allow-downgrades, using a number from the policy list, and restore the archive you took in step 1. Whatever Core stored after that archive was taken does not come back with it.

Licence and telemetry, in plain words

Core's README lets you take its code under either MIT or Apache 2. This is our own general reading and not legal advice. Both let you use it at work, change it and pass it on without publishing your own source; just ship the original copyright line and licence wording with any copy. By default Core sends InfluxData hourly usage figures (CPU and memory use, write and query numbers and more, no data or queries, it says); the block above turns that off.

Questions people ask

Does Core remove old data by itself?

Only with a retention period, which is set when the database is created; Core checks every 30 minutes by default. Without one, nothing expires.

What happens if a drive fails?

With two drives in RAID 1, the server keeps running on the other. Our service agreement covers replacing a failed drive or any other part within four hours of your call or chat.

Can Docker run it instead?

Yes, with the influxdb:3-core image. Publish it as 127.0.0.1:8181:8181, the way the setup guide does. A plain 8181:8181 answers on all addresses, and ufw does not filter it. Pin a tag.