Skip to main content

Setup a bootstrap node

You need to setup an additional edge device as a bootstrap node if mDNS is disabled on your devices or network, or if you are running Actyx on Docker.

Instead of automatically finding other nodes via mDNS, your node will now first connect to the bootstrap node, get a list of all nodes in your swarm from the bootstrap node, and then connect to them.

tip

We advise to always use bootstrap nodes in production deployments to make sure all your nodes connect to each other.

Setup a bootstrap node

Any physical or virtual edge device in your local network can serve as a bootstrap node.

The Actyx bootstrap node is publicly available on Docker Hub. You can download and run an Actyx bootstrap node with the following command:

# Start the bootstrap node with your swarm key
docker run --name actyx_bootstrap_node --rm --env SWARM_KEY=L2tleS9zd2FybS9wc2svMS4wLjAvCi9iYXNlMTYvCjRkNWEzODQ3NGY1MjYzNDc1MjY2NTY3NTMwNTM0NjRkNGUzNzUyNDQ3ODY1NjIzMzRhMzg3MDU4NjU2MTcxNGQ= -p 4001:4001 -v actyx-bootstrap-data:/data actyx/actyx-bootstrap-node
Starting Actyx bootstrap node

Actyx bootstrap node running

bootstrap node address: /ip4/<YOUR_IP>/tcp/4001/p2p/QmQ3iynxmtZUSNF5dvzQQEYhqnB4sqySRej3A2FgiAMBMH

Set the bootstrap node address using the `ax settings set` command on your
Actyx nodes (see https://actyx.com/os/docs/node-settings-schema.html for
more information). Replace <YOUR_IP> above with the IP address of this host.

Press Ctrl+C twice to shutdown this bootstrap node.
Run the bootstrap node with a persistent volume

It is highly recommended to use a persistent volume, as you will otherwise have to change the settings of all your Actyx nodes in this swarm each time you start the bootstrap node. If you want the node's identity to be preserved between runs, you need add a persistent volume with -v for storage of the node's identity. If you do so, the SWARM_KEY environment variable will be ignored in subsequent runs.

Configure your nodes to connect to the bootstrap node

Now that your bootstrap node is running, you can configure nodes in your swarm with it:

The swarm key is a node setting. You can use the output from above and ax settings set to configure it:

ax settings set /swarm/bootstrapNodes [/ip4/192.168.2.225/tcp/4001/p2p/QmQ3iynxmtZUSNF5dvzQQEYhqnB4sqySRej3A2FgiAMBMH] localhost

In case you are running Actyx on Docker without network=host , and your bootstrap node is not running in the same local network as your other nodes, you need to configure the announceAdresses setting on these nodes.