Get started with EDR

This guide takes you from two running InfluxDB 3 Enterprise instances to a replicated point you can query at the destination. It uses EDR’s native binaries and one host with two instances, so you don’t need a second machine to see EDR work.

1. Before you begin
2. Create a token store
3. Configure the source node
4. Configure the destination node
5. Start the agents
6. Verify replication
7. Test recovery
8. Next

Before you begin

Start two InfluxDB 3 Enterprise instances on the host, each on the upgraded storage engine and its own data directory and port—one to act as the EDR source, one as the destination. If you don’t have InfluxDB 3 Enterprise running yet, see Get started with InfluxDB 3 Enterprise.

Also install the EDR binaries on the host. If you’d rather run EDR in containers, see Run EDR in Docker instead of the native steps below—the configuration is the same either way.

EDR runs as a separate agent process (influxdb3-edr) alongside each InfluxDB 3 Enterprise instance, reading its object store directly. The InfluxDB binary itself is unmodified. For the full component and topology model, see EDR architecture.

Create a token store

Each agent resolves its tokens from a token store: a directory of plain-text files, one file per token.

mkdir -p /etc/edr/secrets

# Auth token—identifies the source to the destination.
openssl rand -hex 32 > /etc/edr/secrets/source-auth-token

# Write token—used by the destination's EDR agent to write into its
# local InfluxDB. Typically the destination's InfluxDB admin/operator token.
cp /path/to/destination-write-token /etc/edr/secrets/dest-write-token

For rotation, ownership, and Vault guidance, see Manage tokens.

Configure the source node

# /etc/edr/source-config.yaml
name: "source"

downstream:
  name: "destination"
  address: "http://localhost:9190"     # the destination agent's --listen
  auth_token: "source-auth-token"      # name of file in token store
  historic_fill:
    mode: none                         # required—choose: none | full | since

historic_fill is required on every downstream entry—the agent refuses to start without it. This walkthrough uses mode: none (live-only): EDR replicates only data written after the agent starts, and doesn’t backfill data already on the source. full backfills all pre-existing data before switching to live; since backfills data written after a given time. For the complete semantics, see Configuration file reference.

Configure the destination node

# /etc/edr/destination-config.yaml
name: "destination"

upstreams:
  - name: "source"
    auth_token: "source-auth-token"    # verifies the source's identity
    write_token: "dest-write-token"    # used to write into local InfluxDB

A node needs at least one of the following:

• downstream or downstreams—where it sends data.
• upstreams—who sends it data.

A node with both is a regional relay—see Replicate to InfluxDB 3 Enterprise for multi-hop topologies.

Start the agents

# Source node:
influxdb3-edr \
  --config /etc/edr/source-config.yaml \
  --data-dir 
SOURCE_INSTANCE_DATA_DIR
 \
  --token-store /etc/edr/secrets \
  --listen 0.0.0.0:9090 \
  --state-location /var/lib/edr/source-state

# Destination node:
EDR_WRITE_ENDPOINT="http://localhost:
DESTINATION_INSTANCE_PORT
" \
influxdb3-edr \
  --config /etc/edr/destination-config.yaml \
  --data-dir 
DESTINATION_INSTANCE_DATA_DIR
 \
  --token-store /etc/edr/secrets \
  --listen 0.0.0.0:9190 \
  --state-location /var/lib/edr/destination-state

• SOURCE_INSTANCE_DATA_DIR: the source InfluxDB instance’s data directory
• DESTINATION_INSTANCE_PORT: the destination InfluxDB instance’s HTTP port
• DESTINATION_INSTANCE_DATA_DIR: the destination InfluxDB instance’s data directory

Each influxdb3-edr agent needs its own --data-dir (pointing at its InfluxDB instance’s object store), --listen address, and --state-location, so the two agents on one host don’t collide. See Install EDR for what each flag does.

Verify replication

Use each instance’s own InfluxDB admin or database token—not the EDR auth and write tokens from Create a token store, which authenticate the agents to each other, not you to InfluxDB.

1. Write a point to the source instance:

   curl -X POST "http://localhost:
   SOURCE_INSTANCE_PORT
   /api/v3/write_lp?db=getting_started" \
     --header "Authorization: Bearer 
   SOURCE_INSTANCE_ADMIN_TOKEN
   " \
     --data-raw "edr_test,host=source value=1"

   • SOURCE_INSTANCE_PORT: the source InfluxDB instance’s HTTP port
   • SOURCE_INSTANCE_ADMIN_TOKEN: an admin or database token for the source instance

2. Query the destination instance for the same point:

   curl -G "http://localhost:
   DESTINATION_INSTANCE_PORT
   /api/v3/query_sql" \
     --header "Authorization: Bearer 
   DESTINATION_INSTANCE_ADMIN_TOKEN
   " \
     --data-urlencode "db=getting_started" \
     --data-urlencode "q=SELECT * FROM edr_test"

   • DESTINATION_INSTANCE_PORT: the destination InfluxDB instance’s HTTP port
   • DESTINATION_INSTANCE_ADMIN_TOKEN: an admin or database token for the destination instance

   The point EDR replicated from the source appears in the result.

3. Open http://127.0.0.1:9091/ui on the source host to watch the replication—the embedded UI shows topology, health, and lag. The UI and /metrics bind to loopback by default (--observability-listen); expose them deliberately if you need off-host access. See Monitor EDR.

Test recovery

EDR delivers at-least-once, even across a destination outage:

1. Stop the destination agent.
2. Write more points to the source.
3. Restart the destination agent.

The destination catches up on the backlog it missed while stopped—no data written at the source is lost. See EDR state and recovery for what the agent persists to make this possible. If an agent crashes rather than stopping cleanly, see the log post-mortem playbook to reconstruct what happened from its captured log.

Next

• Run the signals demo—a fuller 4-node topology (edge to regional relay to central hub) that also demonstrates an intermittent link recovering.
• Configuration file reference— scope and bandwidth scheduling for production.
• Replicate to multiple destinations— fan out one source to several destinations at once.
• Monitor EDR—health, historic fill, and gap fill.
• Troubleshoot EDR.