Skip to content

Commit c2fd083

Browse files
achingbrainhugomrdias
achingbrain
and
hugomrdias
authored
docs: consolidate API docs and update readme files (ipfs#2944)
* docs: consolidate API docs and update readme files Moves api docs into `/docs` folder similarly to how js-libp2p has organised their docs. Tries to trim readmes down a bit to make them more digestible and adds links to futher information on different topics. Also reinstates dependency statuses. Co-authored-by: Hugo Dias <[email protected]>
1 parent ae5e506 commit c2fd083

17 files changed

+903
-1704
lines changed

‎ISSUE_TEMPLATE.md

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎README.md

Lines changed: 64 additions & 1043 deletions
Large diffs are not rendered by default.

‎docs/ARCHITECTURE.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# IPFS Architecture
2+
3+
![](../img/architecture.png)
4+
5+
[Annotated version](https://user-images.githubusercontent.com/1211152/47606420-b6265780-da13-11e8-923b-b365a8534e0e.png)
6+
7+
What does this image explain?
8+
9+
- IPFS uses `ipfs-repo` which picks `fs` or `indexeddb` as its storage drivers, depending if it is running in Node.js or in the Browser.
10+
- The exchange protocol, `bitswap`, uses the Block Service which in turn uses the Repo, offering a get and put of blocks to the IPFS implementation.
11+
- The DAG API (previously Object) comes from the IPLD Resolver, it can support several IPLD Formats (i.e: dag-pb, dag-cbor, etc).
12+
- The Files API uses `ipfs-unixfs-engine` to import and export files to and from IPFS.
13+
- libp2p, the network stack of IPFS, uses libp2p to dial and listen for connections, to use the DHT, for discovery mechanisms, and more.
14+
15+
## Code Architecture and folder Structure
16+
17+
![](img/overview.png)
18+
19+
### Source code
20+
21+
```Bash
22+
> tree src -L 2
23+
src # Main source code folder
24+
├── cli # Implementation of the IPFS CLI
25+
│ └── ...
26+
├── http # The HTTP-API implementation of IPFS as defined by HTTP API spec
27+
├── core # IPFS implementation, the core (what gets loaded in browser)
28+
│ ├── components # Each of IPFS subcomponent
29+
│ └── ...
30+
└── ...
31+
```

‎docs/CLI.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# IPFS CLI <!-- omit in toc -->
2+
3+
## Table of contents <!-- omit in toc -->
4+
5+
- [Overview](#overview)
6+
- [Configuration](#configuration)
7+
8+
## Overview
9+
10+
In order to use js-ipfs as a CLI, you must install it with the `global` flag. Run the following (even if you have ipfs installed locally):
11+
12+
```bash
13+
npm install ipfs --global
14+
```
15+
16+
The CLI is available by using the command `jsipfs` in your terminal. This is aliased, instead of using `ipfs`, to make sure it does not conflict with the [Go implementation](https://github.com/ipfs/go-ipfs).
17+
18+
Once installed, please follow the [Getting Started Guide](https://docs.ipfs.io/introduction/usage/) to learn how to initialize your node and run the daemon.
19+
20+
```sh
21+
# Install js-ipfs globally
22+
> jsipfs --help
23+
Commands:
24+
bitswap A set of commands to manipulate the bitswap agent.
25+
block Manipulate raw IPFS blocks.
26+
bootstrap Show or edit the list of bootstrap peers.
27+
commands List all available commands
28+
config <key> [value] Get and set IPFS config values
29+
daemon Start a long-running daemon process
30+
# ...
31+
```
32+
33+
## Configuration
34+
35+
`js-ipfs` uses some different default config values, so that they don't clash directly with a go-ipfs node running in the same machine. These are:
36+
37+
- default repo location: `~/.jsipfs` (can be changed with env variable `IPFS_PATH`)
38+
- default swarm port: `4002`
39+
- default API port: `5002`

‎docs/DAEMON.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
2+
# Running IPFS as a daemon <!-- omit in toc -->
3+
4+
> How to run a long-lived IPFS process
5+
6+
## Table of contents <!-- omit in toc -->
7+
8+
- [CLI](#cli)
9+
- [Programmatic](#programmatic)
10+
11+
## CLI
12+
13+
To start a daemon on the CLI, use the `daemon` command:
14+
15+
```console
16+
jsipfs daemon
17+
```
18+
19+
The IPFS Daemon exposes the API defined in the [HTTP API spec](https://docs.ipfs.io/reference/api/http/). You can use any of the IPFS HTTP-API client libraries with it, such as: [ipfs-http-client](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client).
20+
21+
## Programmatic
22+
23+
If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check out the [ipfsd-ctl](https://github.com/ipfs/js-ipfsd-ctl) module.
24+
25+
```javascript
26+
const { createFactory } = require('ipfsd-ctl')
27+
const factory = createFactory({
28+
type: 'proc' // or 'js' to run in a separate process
29+
})
30+
31+
const node = await factory.create()
32+
33+
// print the node ide
34+
console.info(await node.id())
35+
```

‎docs/DELEGATE_ROUTERS.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Configuring Delegate Routers
2+
3+
If you need to support Delegated Content and/or Peer Routing, you can enable it by specifying the multiaddrs of your delegate nodes in the config via `options.config.Addresses.Delegates`. If you need to run a delegate router we encourage you to run your own, with go-ipfs. You can see instructions for doing so in the [delegated routing example](https://github.com/libp2p/js-libp2p/tree/master/examples/delegated-routing).
4+
5+
If you are not able to run your own delegate router nodes, we currently have two nodes that support delegated routing. **Important**: As many people may be leveraging these nodes, performance may be affected, which is why we recommend running your own nodes in production.
6+
7+
Available delegate multiaddrs are:
8+
- `/dns4/node0.delegate.ipfs.io/tcp/443/https`
9+
- `/dns4/node1.delegate.ipfs.io/tcp/443/https`
10+
11+
**Note**: If more than 1 delegate multiaddr is specified, the actual delegate will be randomly selected on startup.
12+
13+
**Note**: If you wish to use delegated routing and are creating your node _programmatically_ in Node.js or the browser you must `npm install libp2p-delegated-content-routing` and/or `npm install libp2p-delegated-peer-routing` and provide configured instances of them in [`options.libp2p`](#optionslibp2p). See the module repos for further instructions:
14+
15+
- https://github.com/libp2p/js-libp2p-delegated-content-routing
16+
- https://github.com/libp2p/js-libp2p-delegated-peer-routing

‎docs/DEVELOPMENT.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Development <!-- omit in toc -->
2+
3+
> Getting started with development on IPFS
4+
5+
## Table of contents <!-- omit in toc -->
6+
7+
- [Clone and install dependencies](#clone-and-install-dependencies)
8+
- [Run tests](#run-tests)
9+
- [Run interop tests](#run-interop-tests)
10+
- [Run benchmark tests](#run-benchmark-tests)
11+
- [Lint](#lint)
12+
- [Build a dist version](#build-a-dist-version)
13+
14+
## Clone and install dependencies
15+
16+
```sh
17+
> git clone https://github.com/ipfs/js-ipfs.git
18+
> cd js-ipfs
19+
> npm install
20+
```
21+
22+
## Run tests
23+
24+
```sh
25+
# run all the unit tests
26+
> npm test
27+
28+
# run individual tests (findprovs)
29+
> npm run test -- --grep findprovs
30+
31+
# run just IPFS tests in Node.js
32+
> npm run test:node
33+
34+
# run just IPFS core tests
35+
> npm run test:node:core
36+
37+
# run just IPFS HTTP-API tests
38+
> npm run test:node:http
39+
40+
# run just IPFS CLI tests
41+
> npm run test:cli
42+
43+
# run just IPFS core tests in the Browser (Chrome)
44+
> npm run test:browser
45+
46+
# run some interface tests (block API) on Node.js
47+
> npm run test:node:interface -- --grep '.block'
48+
```
49+
50+
### Run interop tests
51+
52+
53+
```sh
54+
# run the interop tests with the default go-IPFS
55+
> npm run test:interop
56+
57+
# run the interop tests with a different go-IPFS
58+
> IPFS_EXEC_GO=/path/to/ipfs npm run test:interop
59+
```
60+
61+
### Run benchmark tests
62+
63+
```sh
64+
# run all the benchmark tests
65+
> npm run benchmark
66+
67+
# run just IPFS benchmarks in Node.js
68+
> npm run benchmark:node
69+
70+
# run just IPFS benchmarks in Node.js for an IPFS instance
71+
> npm run benchmark:node:core
72+
73+
# run just IPFS benchmarks in Node.js for an IPFS daemon
74+
> npm run benchmark:node:http
75+
76+
# run just IPFS benchmarks in the browser (Chrome)
77+
> npm run benchmark:browser
78+
```
79+
80+
## Lint
81+
82+
**Conforming to linting rules is a prerequisite to commit to js-ipfs.**
83+
84+
```sh
85+
> npm run lint
86+
```
87+
88+
## Build a dist version
89+
90+
```sh
91+
> npm run build
92+
```

‎docs/DOCKER.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
2+
# Running js-ipfs with Docker
3+
4+
We have automatic Docker builds setup with Docker Hub: https://hub.docker.com/r/ipfs/js-ipfs/
5+
6+
All branches in the Github repository maps to a tag in Docker Hub, except `master` Git branch which is mapped to `latest` Docker tag.
7+
8+
You can run js-ipfs like this:
9+
10+
```
11+
$ docker run -it -p 4002:4002 -p 4003:4003 -p 5002:5002 -p 9090:9090 ipfs/js-ipfs:latest
12+
13+
initializing ipfs node at /root/.jsipfs
14+
generating 2048-bit RSA keypair...done
15+
peer identity: Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
16+
to get started, enter:
17+
18+
jsipfs files cat /ipfs/QmfGBRT6BbWJd7yUc2uYdaUZJBbnEFvTqehPFoSMQ6wgdr/readme
19+
20+
Initializing daemon...
21+
Using wrtc for webrtc support
22+
Swarm listening on /ip4/127.0.0.1/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
23+
Swarm listening on /ip4/172.17.0.2/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
24+
Swarm listening on /ip4/127.0.0.1/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
25+
Swarm listening on /ip4/172.17.0.2/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
26+
API is listening on: /ip4/0.0.0.0/tcp/5002
27+
Gateway (readonly) is listening on: /ip4/0.0.0.0/tcp/9090
28+
Daemon is ready
29+
30+
$ curl --silent localhost:5002/api/v0/id | jq .ID
31+
"Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS"
32+
```

‎docs/EARLY_TESTERS.md

Lines changed: 0 additions & 32 deletions
This file was deleted.

0 commit comments

Comments
 (0)