Starting the Cluster

Starting an IPFS Cluster peers is a simple process but it must be we well understood as it is one of the places where most mistakes happen.

ipfs-cluster-service daemon starts a cluster peer, but we have to make sure the peer correctly participates and is seen by the rest of the Cluster.

Most considerations when starting a cluster depend on the choice of Consensus component. Currently, the only available Consensus implementation is raft.


raft implementation is very strict about the initialization and maintainance of the peerset. The peerset is the list of peers that make up a Cluster.

When using the raft component, there are two main methods when starting the cluster peers for the first time:

Raft stores and maintains the peerset internally, so once the first start has been successful, any further starts are are simple as running ipfs-cluster-service daemon.

Starting multiple peers with a fixed peerset

This is the recommended way to start a cluster for the first time. This is mostly useful when:

Important: Do not use this method when you need a new peer to join an already running Cluster. If the new peer is not part of the running Cluster's peerset, use the --bootstrap method to add it.



Run the following in all your peers (preferably at once):

$ ipfs-cluster-service daemon

will start the cluster peer:

Starting a single peer and bootstrapping the rest to it

A different, more flexible approach is to start a single peer and then bootstrap other peers to it. As they are bootstrapped, the Cluster will grow with the new peers. This is mostly useful when:

This method is demonstrated in the Quickstart guide.



First start one of the peers with:

$ ipfs-cluster-service daemon

Then bootstrap each of the other peers as explained in the section below:

Bootstrapping a peer

Bootstrapping is the means to safely add peers to a Cluster:

$ ipfs-cluster-service daemon --bootstrap <multiaddress of first peer>

This will bootstrap the peer to an existing one:

Adding peers only works on healthy clusters, with all their peers online. Remove any unhealthy peers before adding new ones.

Restarting clusters and peers

Once your peers have been running and Futher starts are restarts are as simple as running

$ ipfs-cluster-service daemon
Important: Re-starting a peer with `--bootstrap` is not recommended unless it has been removed from the Cluster peerset.

Verifying a good start

The best way to verify your Cluster is up and running correctly is to:

Next steps: Production deployments