2016-07-01 18:41:15 +00:00
# ipfs-cluster
2016-07-01 19:01:27 +00:00
2016-12-02 18:33:39 +00:00
[![ ](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square )](http://ipn.io)
2016-12-08 16:47:43 +00:00
[![ ](https://img.shields.io/badge/project-ipfs-blue.svg?style=flat-square )](http://github.com/ipfs/ipfs)
[![ ](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square )](http://webchat.freenode.net/?channels=%23ipfs)
2016-12-02 18:33:39 +00:00
[![standard-readme compliant ](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square )](https://github.com/RichardLitt/standard-readme)
2016-12-08 16:47:43 +00:00
[![GoDoc ](https://godoc.org/github.com/ipfs/ipfs-cluster?status.svg )](https://godoc.org/github.com/ipfs/ipfs-cluster)
2017-01-24 11:39:08 +00:00
[![Go Report Card ](https://goreportcard.com/badge/github.com/ipfs/ipfs-cluster )](https://goreportcard.com/report/github.com/ipfs/ipfs-cluster)
2016-12-08 16:47:43 +00:00
[![Build Status ](https://travis-ci.org/ipfs/ipfs-cluster.svg?branch=master )](https://travis-ci.org/ipfs/ipfs-cluster)
[![Coverage Status ](https://coveralls.io/repos/github/ipfs/ipfs-cluster/badge.svg?branch=master )](https://coveralls.io/github/ipfs/ipfs-cluster?branch=master)
2016-07-01 19:01:27 +00:00
2017-01-27 12:35:28 +00:00
> Collective pinning and composition for IPFS.
2016-07-01 19:01:27 +00:00
2017-02-27 09:26:50 +00:00
**THIS SOFTWARE IS ALPHA**
2016-07-01 19:01:27 +00:00
2017-02-27 09:26:50 +00:00
`ipfs-cluster` allows to replicate content (by pinning) in multiple IPFS nodes:
2016-10-10 16:43:59 +00:00
2017-02-27 09:26:50 +00:00
* Works on top of the IPFS daemon by running one cluster peer per IPFS node (`ipfs-cluster-service`)
* A `replication_factor` controls how many times a CID is pinned in the cluster
2017-03-02 14:12:06 +00:00
* Re-pins stuff in a different place when a peer goes down
2017-02-27 09:26:50 +00:00
* Provides an HTTP API and a command-line wrapper (`ipfs-cluster-ctl`)
* Provides an IPFS daemon API Proxy which intercepts any "pin"/"unpin" requests and does cluster pinning instead
2017-03-02 14:12:06 +00:00
* The IPFS Proxy allows to build cluster composition, with a cluster peer acting as an IPFS daemon for another higher-level cluster.
2017-02-27 09:26:50 +00:00
* Peers share the state using Raft-based consensus. Uses the LibP2P stack (`go-libp2p-raft`, `go-libp2p-rpc` ...)
2016-10-10 16:43:59 +00:00
2016-12-02 18:33:39 +00:00
## Table of Contents
2016-10-10 16:43:59 +00:00
2017-02-15 14:16:16 +00:00
- [Maintainers and Roadmap ](#maintainers-and-roadmap )
2016-12-02 18:33:39 +00:00
- [Install ](#install )
- [Usage ](#usage )
2017-01-30 12:12:25 +00:00
- [`ipfs-cluster-service` ](#ipfs-cluster-service )
- [`ipfs-cluster-ctl` ](#ipfs-cluster-ctl )
2017-02-27 09:26:50 +00:00
- [`Go` ](#go )
- [`Additional docs` ](#additional-docs )
2016-12-02 18:33:39 +00:00
- [API ](#api )
2017-02-27 09:26:50 +00:00
- [Architecture ](#api )
2016-12-02 18:33:39 +00:00
- [Contribute ](#contribute )
- [License ](#license )
2017-02-15 14:16:16 +00:00
## Maintainers and Roadmap
2017-01-23 12:16:20 +00:00
2017-01-27 14:32:29 +00:00
This project is captained by [@hsanjuan ](https://github.com/hsanjuan ). See the [captain's log ](CAPTAIN.LOG.md ) for a written summary of current status and upcoming features. You can also check out the project's [Roadmap ](ROADMAP.md ) for a high level overview of what's coming and the project's [Waffle Board ](https://waffle.io/ipfs/ipfs-cluster ) to see what issues are being worked on at the moment.
2017-01-23 12:16:20 +00:00
2016-12-02 18:33:39 +00:00
## Install
2017-02-27 09:26:50 +00:00
`ipfs-cluster` is written in Go. In order to install the `ipfs-cluster-service` the `ipfs-cluster-ctl` tool simply download this repository and run `make` as follows:
2016-12-21 19:04:28 +00:00
```
$ go get -u -d github.com/ipfs/ipfs-cluster
$ cd $GOPATH/src/github.com/ipfs/ipfs-cluster
$ make install
```
2017-02-27 09:26:50 +00:00
This will install `ipfs-cluster-service` and `ipfs-cluster-ctl` in your `$GOPATH/bin` folder. See the usage below.
2016-12-02 18:33:39 +00:00
## Usage
2017-01-23 12:34:22 +00:00
### `ipfs-cluster-service`
2016-12-21 19:04:28 +00:00
2017-03-03 16:52:43 +00:00
For information on how to configure and launch an IPFS Cluster peer see the [`ipfs-cluster-service` README ](ipfs-cluster-service/dist/README.md ).
2016-12-21 19:04:28 +00:00
2017-01-23 12:34:22 +00:00
### `ipfs-cluster-ctl`
2016-12-21 19:04:28 +00:00
2017-03-03 16:52:43 +00:00
For information on how to manage and perform operations on an IPFS Cluster peer see the [`ipfs-cluster-ctl` README ](ipfs-cluster-ctl/dist/README.md ).
2017-01-27 12:30:15 +00:00
2017-02-27 09:26:50 +00:00
### Go
2017-01-30 12:12:25 +00:00
2017-02-27 09:26:50 +00:00
IPFS Cluster nodes can be launched directly from Go. The `Cluster` object provides methods to interact with the cluster and perform actions.
2017-01-30 12:12:25 +00:00
2017-02-27 09:26:50 +00:00
Documentation and examples on how to use IPFS Cluster from Go can be found in [godoc.org/github.com/ipfs/ipfs-cluster ](https://godoc.org/github.com/ipfs/ipfs-cluster ).
2017-01-30 12:12:25 +00:00
2017-02-27 09:26:50 +00:00
### Additional docs
2017-01-30 12:12:25 +00:00
2017-02-27 09:26:50 +00:00
You can find more information and detailed guides:
2016-12-21 19:04:28 +00:00
2017-02-27 09:26:50 +00:00
* [Building and updating an IPFS Cluster ](docs/HOWTO_build_and_update_a_cluster.md )
2016-12-02 18:33:39 +00:00
2017-02-27 09:26:50 +00:00
Note: please contribute to improve and add more documentation!
2016-12-02 18:33:39 +00:00
## API
2016-12-21 19:04:28 +00:00
TODO: Swagger
2016-12-02 18:33:39 +00:00
2017-01-27 12:30:15 +00:00
This is a quick summary of API endpoints offered by the Rest API component (these may change before 1.0):
|Method|Endpoint |Comment|
|------|--------------------|-------|
|GET |/id |Cluster peer information|
|GET |/version |Cluster version|
|GET |/peers |Cluster peers|
2017-01-30 12:12:25 +00:00
|POST |/peers |Add new peer|
|DELETE|/peers/{peerID} |Remove a peer|
2017-01-27 12:30:15 +00:00
|GET |/pinlist |List of pins in the consensus state|
|GET |/pins |Status of all tracked CIDs|
|POST |/pins/sync |Sync all|
|GET |/pins/{cid} |Status of single CID|
|POST |/pins/{cid} |Pin CID|
|DELETE|/pins/{cid} |Unpin CID|
|POST |/pins/{cid}/sync |Sync CID|
|POST |/pins/{cid}/recover |Recover CID|
2017-02-15 14:16:16 +00:00
## Architecture
The best place to get an overview of how cluster works, what components exist etc. is the [architecture.md ](architecture.md ) doc.
2016-12-02 18:33:39 +00:00
## Contribute
PRs accepted.
Small note: If editing the README, please conform to the [standard-readme ](https://github.com/RichardLitt/standard-readme ) specification.
## License
MIT © Protocol Labs, Inc.