Issue #55: Move tooling information to it's own README in the subprojects.
Add LICENSE there too, so that the build tool for distributions includes it in the tar files. License: MIT Signed-off-by: Hector Sanjuan <hector@protocol.ai>
This commit is contained in:
Hector Sanjuan
parent
e038ea039a
commit
85651ae8cb
76
README.md
76
README.md
|
|
@ -61,83 +61,11 @@ This will install `ipfs-cluster-service` and `ipfs-cluster-ctl` in your `$GOPATH
|
|||
|
||||
### `ipfs-cluster-service`
|
||||
|
||||
`ipfs-cluster-service` runs a cluster peer. Usage information can be obtained running:
|
||||
|
||||
```
|
||||
$ ipfs-cluster-service -h
|
||||
```
|
||||
|
||||
Before running `ipfs-cluster-service` for the first time, initialize a configuration file with:
|
||||
|
||||
```
|
||||
$ ipfs-cluster-service -init
|
||||
```
|
||||
|
||||
The configuration will be placed in `~/.ipfs-cluster/service.json` by default.
|
||||
|
||||
You can add the multiaddresses for the other cluster peers the `bootstrap` variable. For example, here is a valid configuration for a single-peer cluster:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "QmXMhZ53zAoes8TYbKGn3rnm5nfWs5Wdu41Fhhfw9XmM5A",
|
||||
"private_key": "<redacted>",
|
||||
"cluster_peers": [],
|
||||
"bootstrap": [],
|
||||
"leave_on_shutdown": false,
|
||||
"cluster_multiaddress": "/ip4/0.0.0.0/tcp/9096",
|
||||
"api_listen_multiaddress": "/ip4/127.0.0.1/tcp/9094",
|
||||
"ipfs_proxy_listen_multiaddress": "/ip4/127.0.0.1/tcp/9095",
|
||||
"ipfs_node_multiaddress": "/ip4/127.0.0.1/tcp/5001",
|
||||
"consensus_data_folder": "/home/user/.ipfs-cluster/data",
|
||||
"state_sync_seconds": 60,
|
||||
"replication_factor": -1
|
||||
}
|
||||
```
|
||||
|
||||
The configuration file should probably be identical among all cluster peers, except for the `id` and `private_key` fields. Once every cluster peer has the configuration in place, you can run `ipfs-cluster-service` to start the cluster. See the [additional docs](#additional-docs) section for detailed documentation on how to build a cluster.
|
||||
|
||||
#### Clusters using `cluster_peers`
|
||||
|
||||
The `cluster_peers` configuration variable holds a list of current cluster members. If you know the members of the cluster in advance, or you want to start a cluster fully in parallel, set `cluster_peers` in all configurations so that every peer knows the rest upon boot. Leave `bootstrap` empty. A cluster peer address looks like: `/ip4/1.2.3.4/tcp/9096/<id>`.
|
||||
|
||||
#### Clusters using `bootstrap`
|
||||
|
||||
When the `cluster_peers` variable is empty, the multiaddresses `bootstrap` can be used to have a peer join an existing cluster. The peer will contact those addresses (in order) until one of them succeeds in joining it to the cluster. When the peer is shut down, it will save the current cluster peers in the `cluster_peers` configuration variable for future use.
|
||||
|
||||
Bootstrap is a convenient method, but more prone to errors than `cluster_peers`. It can be used as well with `ipfs-cluster-service --bootstrap <multiaddress>`. Note that bootstrapping nodes with an old state (or diverging state) from the one running in the cluster may lead to problems with
|
||||
the consensus, so usually you would want to bootstrap blank nodes.
|
||||
|
||||
#### Debugging
|
||||
|
||||
`ipfs-cluster-service` offers two debugging options:
|
||||
|
||||
* `--debug` enables debug logging from the `ipfs-cluster`, `go-libp2p-raft` and `go-libp2p-rpc` layers. This will be a very verbose log output, but at the same time it is the most informative.
|
||||
* `--loglevel` sets the log level (`[error, warning, info, debug]`) for the `ipfs-cluster` only, allowing to get an overview of the what cluster is doing. The default log-level is `info`.
|
||||
For information on how to configure and launch an IPFS Cluster peer see the [`ipfs-cluster-service` README](ipfs-cluster-service/README.md).
|
||||
|
||||
### `ipfs-cluster-ctl`
|
||||
|
||||
`ipfs-cluster-ctl` is the client application to manage the cluster nodes and perform actions. `ipfs-cluster-ctl` uses the HTTP API provided by the nodes and it is completely separate from the cluster service. It can talk to any cluster peer (`--host`) and uses `localhost` by default.
|
||||
|
||||
After installing, you can run `ipfs-cluster-ctl --help` to display general description and options, or alternatively `ipfs-cluster-ctl help [cmd]` to display
|
||||
information about supported commands.
|
||||
|
||||
In summary, it works as follows:
|
||||
|
||||
```
|
||||
$ ipfs-cluster-ctl id # show cluster peer and ipfs daemon information
|
||||
$ ipfs-cluster-ctl peers ls # list cluster peers
|
||||
$ ipfs-cluster-ctl peers add /ip4/1.2.3.4/tcp/1234/<peerid> # add a new cluster peer
|
||||
$ ipfs-cluster-ctl peers rm <peerid> # remove a cluster peer
|
||||
$ ipfs-cluster-ctl pin add Qma4Lid2T1F68E3Xa3CpE6vVJDLwxXLD8RfiB9g1Tmqp58 # pins a CID in the cluster
|
||||
$ ipfs-cluster-ctl pin rm Qma4Lid2T1F68E3Xa3CpE6vVJDLwxXLD8RfiB9g1Tmqp58 # unpins a CID from the cluster
|
||||
$ ipfs-cluster-ctl status # display tracked CIDs information
|
||||
$ ipfs-cluster-ctl sync Qma4Lid2T1F68E3Xa3CpE6vVJDLwxXLD8RfiB9g1Tmqp58 # sync information from the IPFS daemon
|
||||
$ ipfs-cluster-ctl recover Qma4Lid2T1F68E3Xa3CpE6vVJDLwxXLD8RfiB9g1Tmqp58 # attempt to re-pin/unpin CIDs in error state
|
||||
```
|
||||
|
||||
#### Debugging
|
||||
|
||||
`ipfs-cluster-ctl` provides a `--debug` flag which allows to inspect request paths and raw response bodies.
|
||||
For information on how to manage and perform operations on an IPFS Cluster peer see the [`ipfs-cluster-ctl` README](ipfs-cluster-ctl/README.md).
|
||||
|
||||
### Go
|
||||
|
||||
|
|
|
|||
|
|
@ -142,7 +142,7 @@ type JSONConfig struct {
|
|||
|
||||
// Number of seconds between monitoring checks which detect
|
||||
// if a peer is down and consenquently trigger a rebalance
|
||||
MonitoringIntervalSeconds int `json:"monitoring_interval"`
|
||||
MonitoringIntervalSeconds int `json:"monitoring_interval_seconds"`
|
||||
}
|
||||
|
||||
// ToJSONConfig converts a Config object to its JSON representation which
|
||||
|
|
|
|||
21
ipfs-cluster-ctl/LICENSE
Normal file
21
ipfs-cluster-ctl/LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2017 Protocol Labs, Inc
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
33
ipfs-cluster-ctl/README.md
Normal file
33
ipfs-cluster-ctl/README.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# `ipfs-cluster-ctl`
|
||||
|
||||
> IPFS cluster management tool
|
||||
|
||||
`ipfs-cluster-ctl` is the client application to manage the cluster nodes and perform actions. `ipfs-cluster-ctl` uses the HTTP API provided by the nodes and it is completely separate from the cluster service.
|
||||
|
||||
|
||||
### Usage
|
||||
|
||||
Usage information can be obtained by running:
|
||||
|
||||
```
|
||||
$ ipfs-cluster-ctl --help
|
||||
```
|
||||
|
||||
You can also obtain command-specific help with `ipfs-cluster-ctl help [cmd]`. The (`--host`) can be used to talk to any remote cluster peer (`localhost` is used by default). In summary, it works as follows:
|
||||
|
||||
|
||||
```
|
||||
$ ipfs-cluster-ctl id # show cluster peer and ipfs daemon information
|
||||
$ ipfs-cluster-ctl peers ls # list cluster peers
|
||||
$ ipfs-cluster-ctl peers add /ip4/1.2.3.4/tcp/1234/<peerid> # add a new cluster peer
|
||||
$ ipfs-cluster-ctl peers rm <peerid> # remove a cluster peer
|
||||
$ ipfs-cluster-ctl pin add Qma4Lid2T1F68E3Xa3CpE6vVJDLwxXLD8RfiB9g1Tmqp58 # pins a CID in the cluster
|
||||
$ ipfs-cluster-ctl pin rm Qma4Lid2T1F68E3Xa3CpE6vVJDLwxXLD8RfiB9g1Tmqp58 # unpins a CID from the cluster
|
||||
$ ipfs-cluster-ctl status # display tracked CIDs information
|
||||
$ ipfs-cluster-ctl sync Qma4Lid2T1F68E3Xa3CpE6vVJDLwxXLD8RfiB9g1Tmqp58 # sync information from the IPFS daemon
|
||||
$ ipfs-cluster-ctl recover Qma4Lid2T1F68E3Xa3CpE6vVJDLwxXLD8RfiB9g1Tmqp58 # attempt to re-pin/unpin CIDs in error state
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
`ipfs-cluster-ctl` takes a `--debug` flag which allows to inspect request paths and raw response bodies.
|
||||
21
ipfs-cluster-service/LICENSE
Normal file
21
ipfs-cluster-service/LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2017 Protocol Labs, Inc
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
66
ipfs-cluster-service/README.md
Normal file
66
ipfs-cluster-service/README.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# `ipfs-cluster-service`
|
||||
|
||||
> IPFS cluster peer launcher
|
||||
|
||||
`ipfs-cluster-service` runs a full IPFS Cluster peer.
|
||||
|
||||
### Usage
|
||||
|
||||
Usage information can be obtained with:
|
||||
|
||||
```
|
||||
$ ipfs-cluster-service -h
|
||||
```
|
||||
|
||||
### Initialization
|
||||
|
||||
Before running `ipfs-cluster-service` for the first time, initialize a configuration file with:
|
||||
|
||||
```
|
||||
$ ipfs-cluster-service init
|
||||
```
|
||||
|
||||
|
||||
### Configuration
|
||||
|
||||
After initialization, the configuration will be placed in `~/.ipfs-cluster/service.json` by default.
|
||||
|
||||
You can add the multiaddresses for the other cluster peers the `bootstrap` variable. For example, here is a valid configuration for a single-peer cluster:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "QmXMhZ53zAoes8TYbKGn3rnm5nfWs5Wdu41Fhhfw9XmM5A",
|
||||
"private_key": "<redacted>",
|
||||
"cluster_peers": [],
|
||||
"bootstrap": [],
|
||||
"leave_on_shutdown": false,
|
||||
"cluster_multiaddress": "/ip4/0.0.0.0/tcp/9096",
|
||||
"api_listen_multiaddress": "/ip4/127.0.0.1/tcp/9094",
|
||||
"ipfs_proxy_listen_multiaddress": "/ip4/127.0.0.1/tcp/9095",
|
||||
"ipfs_node_multiaddress": "/ip4/127.0.0.1/tcp/5001",
|
||||
"consensus_data_folder": "/home/user/.ipfs-cluster/data",
|
||||
"state_sync_seconds": 60,
|
||||
"replication_factor": -1,
|
||||
"monitoring_interval_seconds": 15
|
||||
}
|
||||
```
|
||||
|
||||
The configuration file should probably be identical among all cluster peers, except for the `id` and `private_key` fields. Once every cluster peer has the configuration in place, you can run `ipfs-cluster-service` to start the cluster. See the [additional docs](#additional-docs) section for detailed documentation on how to build a cluster.
|
||||
|
||||
#### Clusters using `cluster_peers`
|
||||
|
||||
The `cluster_peers` configuration variable holds a list of current cluster members. If you know the members of the cluster in advance, or you want to start a cluster fully in parallel, set `cluster_peers` in all configurations so that every peer knows the rest upon boot. Leave `bootstrap` empty. A cluster peer address looks like: `/ip4/1.2.3.4/tcp/9096/<id>`.
|
||||
|
||||
#### Clusters using `bootstrap`
|
||||
|
||||
When the `cluster_peers` variable is empty, the multiaddresses `bootstrap` can be used to have a peer join an existing cluster. The peer will contact those addresses (in order) until one of them succeeds in joining it to the cluster. When the peer is shut down, it will save the current cluster peers in the `cluster_peers` configuration variable for future use.
|
||||
|
||||
Bootstrap is a convenient method, but more prone to errors than `cluster_peers`. It can be used as well with `ipfs-cluster-service --bootstrap <multiaddress>`. Note that bootstrapping nodes with an old state (or diverging state) from the one running in the cluster may lead to problems with
|
||||
the consensus, so usually you would want to bootstrap blank nodes.
|
||||
|
||||
### Debugging
|
||||
|
||||
`ipfs-cluster-service` offers two debugging options:
|
||||
|
||||
* `--debug` enables debug logging from the `ipfs-cluster`, `go-libp2p-raft` and `go-libp2p-rpc` layers. This will be a very verbose log output, but at the same time it is the most informative.
|
||||
* `--loglevel` sets the log level (`[error, warning, info, debug]`) for the `ipfs-cluster` only, allowing to get an overview of the what cluster is doing. The default log-level is `info`.
|
||||
Loading…
Reference in New Issue
Block a user