Starting the Cluster

Starting a IPFS Cluster peers for the first time 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 bootstrapping needs to happen the first time the other peers are started for them to become part of the same cluster.

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 most of their peers online.

Note that once your peer has bootstrapped once to the cluster, you can just start it normally with ipfs-cluster-service daemon the next time.

Restarting clusters and peers

Once your peers have been running 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