storj/README.md

132 lines
6.1 KiB
Markdown
Raw Normal View History

2018-08-20 20:46:45 +01:00
# Storj V3 Network
2018-04-06 17:32:34 +01:00
[![Go Report Card](https://goreportcard.com/badge/storj.io/storj)](https://goreportcard.com/report/storj.io/storj)
[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://pkg.go.dev/storj.io/storj)
2020-12-28 21:59:06 +00:00
[![Coverage Status](https://img.shields.io/badge/coverage-master-green.svg)](https://build.dev.storj.io/job/storj/job/main/cobertura)
![Alpha](https://img.shields.io/badge/version-alpha-green.svg)
2018-04-06 17:32:34 +01:00
2020-12-28 21:59:06 +00:00
<img src="https://github.com/storj/storj/raw/main/resources/logo.png" width="100">
2018-04-06 17:32:34 +01:00
Storj is building a decentralized cloud storage network.
[Check out our white paper for more info!](https://storj.io/storj.pdf)
2018-04-06 17:32:34 +01:00
----
2018-10-30 01:50:38 +00:00
Storj is an S3-compatible platform and suite of decentralized applications that
allows you to store data in a secure and decentralized manner. Your files are
encrypted, broken into little pieces and stored in a global decentralized
network of computers. Luckily, we also support allowing you (and only you) to
retrieve those files!
2018-04-06 17:32:34 +01:00
## Table of Contents
- [Contributing](#contributing-to-storj)
2018-10-30 01:50:38 +00:00
- [Start using Storj](#start-using-storj)
- [License](#license)
- [Support](#support)
# Contributing to Storj
[![](https://sourcerer.io/fame/jtolds/storj/storj/images/0)](https://sourcerer.io/fame/jtolds/storj/storj/links/0)[![](https://sourcerer.io/fame/jtolds/storj/storj/images/1)](https://sourcerer.io/fame/jtolds/storj/storj/links/1)[![](https://sourcerer.io/fame/jtolds/storj/storj/images/2)](https://sourcerer.io/fame/jtolds/storj/storj/links/2)[![](https://sourcerer.io/fame/jtolds/storj/storj/images/3)](https://sourcerer.io/fame/jtolds/storj/storj/links/3)[![](https://sourcerer.io/fame/jtolds/storj/storj/images/4)](https://sourcerer.io/fame/jtolds/storj/storj/links/4)[![](https://sourcerer.io/fame/jtolds/storj/storj/images/5)](https://sourcerer.io/fame/jtolds/storj/storj/links/5)[![](https://sourcerer.io/fame/jtolds/storj/storj/images/6)](https://sourcerer.io/fame/jtolds/storj/storj/links/6)[![](https://sourcerer.io/fame/jtolds/storj/storj/images/7)](https://sourcerer.io/fame/jtolds/storj/storj/links/7)
2018-10-30 01:50:38 +00:00
All of our code for Storj v3 is open source. Have a code change you think would make Storj better? Please send a pull request along! Make sure to sign our [Contributor License Agreement (CLA)](https://docs.google.com/forms/d/e/1FAIpQLSdVzD5W8rx-J_jLaPuG31nbOzS8yhNIIu4yHvzonji6NeZ4ig/viewform) first. See our [license section](#license) for more details.
Have comments or bug reports? Want to propose a PR before hand-crafting it? Jump on to our [forum](https://forum.storj.io) and join the [Engineering Discussions](https://forum.storj.io/c/engineer-amas) to say hi to the developer community and to talk to the Storj core team.
Want to vote on or suggest new features? Post it on the [forum](https://forum.storj.io/c/parent-cat/5).
2018-04-06 17:32:34 +01:00
### Issue tracking and roadmap
See the breakdown of what we're building by checking out the following resources:
2019-02-25 14:09:44 +00:00
* [White paper](https://storj.io/whitepaper)
### Install required packages
2018-04-17 14:38:31 +01:00
To get started running Storj locally, download and install the latest release of Go (at least Go 1.13) at [golang.org](https://golang.org).
2018-04-17 14:38:31 +01:00
You will also need [Git](https://git-scm.com/). (`brew install git`, `apt-get install git`, etc).
If you're building on Windows, you also need to install and have [gcc](https://gcc.gnu.org/install/binaries.html) setup correctly.
We support Linux, Mac, and Windows operating systems. Other operating systems supported by Go should also be able to run Storj.
### Download and compile Storj
> **Aside about GOPATH**: Go 1.11 supports a new feature called Go modules,
> and Storj has adopted Go module support. If you've used previous Go versions,
> Go modules no longer require a GOPATH environment variable. Go by default
> falls back to the old behavior if you check out code inside of the directory
> referenced by your GOPATH variable, so make sure to use another directory,
> `unset GOPATH` entirely, or set `GO111MODULE=on` before continuing with these
> instructions.
2018-10-30 01:50:38 +00:00
First, fork our repo and clone your copy of our repository.
```bash
2018-10-30 01:50:38 +00:00
git clone git@github.com:<your-username>/storj storj
cd storj
```
Then, let's install Storj.
```bash
go install -v ./cmd/...
```
2018-10-30 01:50:38 +00:00
### Make changes and test
2018-10-30 01:50:38 +00:00
Make the changes you want to see! Once you're done, you can run all of the unit tests:
2018-08-01 22:18:09 +01:00
2018-07-31 18:13:32 +01:00
```bash
go test -v ./...
2018-07-31 18:13:32 +01:00
```
You can also execute only a single test package if you like. For example:
Remove Kademlia dependencies from Satellite and Storagenode (#2966) What: cmd/inspector/main.go: removes kad commands internal/testplanet/planet.go: Waits for contact chore to finish satellite/contact/nodesservice.go: creates an empty nodes service implementation satellite/contact/service.go: implements Local and FetchInfo methods & adds external address config value satellite/discovery/service.go: replaces kad.FetchInfo with contact.FetchInfo in Refresh() & removes Discover() satellite/peer.go: sets up contact service and endpoints storagenode/console/service.go: replaces nodeID with contact.Local() storagenode/contact/chore.go: replaces routing table with contact service storagenode/contact/nodesservice.go: creates empty implementation for ping and request info nodes service & implements RequestInfo method storagenode/contact/service.go: creates a service to return the local node and update its own capacity storagenode/monitor/monitor.go: uses contact service in place of routing table storagenode/operator.go: moves operatorconfig from kad into its own setup storagenode/peer.go: sets up contact service, chore, pingstats and endpoints satellite/overlay/config.go: changes NodeSelectionConfig.OnlineWindow default to 4hr to allow for accurate repair selection Removes kademlia setups in: cmd/storagenode/main.go cmd/storj-sim/network.go internal/testplane/planet.go internal/testplanet/satellite.go internal/testplanet/storagenode.go satellite/peer.go scripts/test-sim-backwards.sh scripts/testdata/satellite-config.yaml.lock storagenode/inspector/inspector.go storagenode/peer.go storagenode/storagenodedb/database.go Why: Replacing Kademlia Please describe the tests: • internal/testplanet/planet_test.go: TestBasic: assert that the storagenode can check in with the satellite without any errors TestContact: test that all nodes get inserted into both satellites' overlay cache during testplanet setup • satellite/contact/contact_test.go: TestFetchInfo: Tests that the FetchInfo method returns the correct info • storagenode/contact/contact_test.go: TestNodeInfoUpdated: tests that the contact chore updates the node information TestRequestInfoEndpoint: tests that the Request info endpoint returns the correct info Please describe the performance impact: Node discovery should be at least slightly more performant since each node connects directly to each satellite and no longer needs to wait for bootstrapping. It probably won't be faster in real time on start up since each node waits a random amount of time (less than 1 hr) to initialize its first connection (jitter).
2019-09-19 20:56:34 +01:00
`go test ./pkg/identity`. Add `-v` for more informations about the executed unit
tests.
2018-04-06 17:32:34 +01:00
2018-10-30 01:50:38 +00:00
### Push up a pull request
2018-10-30 01:50:38 +00:00
Use Git to push your changes to your fork:
```bash
2018-10-30 01:50:38 +00:00
git commit -a -m 'my changes!'
2020-12-28 21:59:06 +00:00
git push origin main
```
2018-10-30 01:50:38 +00:00
Use Github to open a pull request!
2020-03-26 00:53:11 +00:00
### A Note about Versioning
While we are practicing [semantic versioning](https://semver.org/) for our client
libraries such as [uplink](https://github.com/storj/uplink), we are *not* practicing
semantic versioning in this repo, as we do not intend for it to be used via
[Go modules](https://blog.golang.org/using-go-modules). We may have
2020-03-26 00:53:11 +00:00
backwards-incompatible changes between minor and patch releases in this repo.
2018-10-30 01:50:38 +00:00
# Start using Storj
2018-12-30 02:02:55 +00:00
Our wiki has [documentation and tutorials](https://github.com/storj/storj/wiki).
2018-10-30 01:50:38 +00:00
Check out these three tutorials:
2018-12-30 02:02:55 +00:00
* [Using the Storj Test Network](https://github.com/storj/storj/wiki/Test-network)
* [Using the Uplink CLI](https://github.com/storj/storj/wiki/Uplink-CLI)
* [Using the S3 Gateway](https://github.com/storj/storj/wiki/S3-Gateway)
# License
2018-10-25 08:02:52 +01:00
The network under construction (this repo) is currently licensed with the
[AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) license. Once the network
reaches beta phase, we will be licensing all client-side code via the
[Apache v2](https://www.apache.org/licenses/LICENSE-2.0) license.
2018-10-30 01:50:38 +00:00
For code released under the AGPLv3, we request that contributors sign our
[Contributor License Agreement (CLA)](https://docs.google.com/forms/d/e/1FAIpQLSdVzD5W8rx-J_jLaPuG31nbOzS8yhNIIu4yHvzonji6NeZ4ig/viewform) so that we can relicense the
code under Apache v2, or other licenses in the future.
# Support
2018-04-06 17:32:34 +01:00
If you have any questions or suggestions please reach out to us on
[our community forum](https://forum.storj.io/) or file a ticket at
https://support.storj.io/.