docs: README refresh, add cli-http-api-core diagram
License: MIT Signed-off-by: diasdavid <daviddias.p@gmail.com>
David Dias committed
Aug 22, 2018 at 20:03 UTC
dae6189bd8db7e9bb9db6efe0efc0379c6cc9fc8
3 files changed
+79
-109
README.md
+79
-47
@@ -9,8 +9,6 @@
9
[](https://godoc.org/github.com/ipfs/go-ipfs)
10
[](https://travis-ci.org/ipfs/go-ipfs)
11
12
-> IPFS implementation in Go
13
-
12
## Project Status
13
14
[](https://waffle.io/ipfs/go-ipfs/metrics/throughput)
@@ -39,15 +37,14 @@ Please put all issues regarding:
37
- [Download and Compile IPFS](#download-and-compile-ipfs)
38
- [Troubleshooting](#troubleshooting)
39
- [Development Dependencies](#development-dependencies)
42
- - [Updating](#updating)
40
+ - [Updating](#updating-go-ipfs)
41
- [Usage](#usage)
42
- [Getting Started](#getting-started)
43
- [Some things to try](#some-things-to-try)
44
- [Docker usage](#docker-usage)
45
- [Troubleshooting](#troubleshooting-1)
46
+- [Development](#development)
47
- [Contributing](#contributing)
49
- - [Want to hack on IPFS?](#want-to-hack-on-ipfs)
50
- - [Want to read our code?](#want-to-read-our-code)
48
- [License](#license)
49
50
## Security Issues
@@ -88,13 +85,15 @@ You can also download go-ipfs from this project's GitHub releases page if you ar
85
In Arch Linux go-ipfs is available as
86
[go-ipfs](https://www.archlinux.org/packages/community/x86_64/go-ipfs/) package.
87
91
- $ sudo pacman -S go-ipfs
88
+```
89
+$ sudo pacman -S go-ipfs
90
+```
91
92
Development version of go-ipfs is also on AUR under
93
[go-ipfs-git](https://aur.archlinux.org/packages/go-ipfs-git/).
94
You can install it using your favourite AUR Helper or manually from AUR.
95
97
-### Nix
96
+#### Nix
97
98
For Linux and MacOSX you can use the purely functional package manager [Nix](https://nixos.org/nix/):
99
@@ -107,7 +106,9 @@ You can also install the Package by using it's attribute name, which is also `ip
106
107
With snap, in any of the [supported Linux distributions](https://snapcraft.io/docs/core/install):
108
110
- $ sudo snap install ipfs
109
+```
110
+$ sudo snap install ipfs
111
+```
112
113
### Build from Source
114
@@ -115,7 +116,6 @@ With snap, in any of the [supported Linux distributions](https://snapcraft.io/do
116
117
The build process for ipfs requires Go 1.10 or higher. If you don't have it: [Download Go 1.10+](https://golang.org/dl/).
118
118
-
119
You'll need to add Go's bin directories to your `$PATH` environment variable e.g., by adding these lines to your `/etc/profile` (for a system-wide installation) or `$HOME/.profile`:
120
121
```
@@ -153,43 +153,44 @@ mismatched APIs.
153
154
#### Troubleshooting
155
156
-* Separate [instructions are available for building on Windows](docs/windows.md).
157
-* Also, [instructions for OpenBSD](docs/openbsd.md).
158
-* `git` is required in order for `go get` to fetch all dependencies.
159
-* Package managers often contain out-of-date `golang` packages.
156
+- Separate [instructions are available for building on Windows](docs/windows.md).
157
+- Also, [instructions for OpenBSD](docs/openbsd.md).
158
+- `git` is required in order for `go get` to fetch all dependencies.
159
+- Package managers often contain out-of-date `golang` packages.
160
Ensure that `go version` reports at least 1.10. See above for how to install go.
161
-* If you are interested in development, please install the development
161
+- If you are interested in development, please install the development
162
dependencies as well.
163
-* *WARNING: Older versions of OSX FUSE (for Mac OS X) can cause kernel panics when mounting!*
163
+- _WARNING_: Older versions of OSX FUSE (for Mac OS X) can cause kernel panics when mounting!-
164
We strongly recommend you use the [latest version of OSX FUSE](http://osxfuse.github.io/).
165
(See https://github.com/ipfs/go-ipfs/issues/177)
166
-* For more details on setting up FUSE (so that you can mount the filesystem), see the docs folder.
167
-* Shell command completion is available in `misc/completion/ipfs-completion.bash`. Read [docs/command-completion.md](docs/command-completion.md) to learn how to install it.
168
-* See the [init examples](https://github.com/ipfs/website/tree/master/static/docs/examples/init) for how to connect IPFS to systemd or whatever init system your distro uses.
169
-
170
-### Development Dependencies
166
+- For more details on setting up FUSE (so that you can mount the filesystem), see the docs folder.
167
+- Shell command completion is available in `misc/completion/ipfs-completion.bash`. Read [docs/command-completion.md](docs/command-completion.md) to learn how to install it.
168
+- See the [init examples](https://github.com/ipfs/website/tree/master/static/docs/examples/init) for how to connect IPFS to systemd or whatever init system your distro uses.
169
172
-If you make changes to the protocol buffers, you will need to install the [protoc compiler](https://github.com/google/protobuf).
170
+### Updating go-ipfs
171
174
-### Updating
172
+#### Using ipfs-update
173
176
-#### Updating using ipfs-update
174
IPFS has an updating tool that can be accessed through `ipfs update`. The tool is
175
not installed alongside IPFS in order to keep that logic independent of the main
176
codebase. To install `ipfs update`, [download it here](https://ipfs.io/ipns/dist.ipfs.io/#ipfs-update).
177
178
#### Downloading IPFS builds using IPFS
179
+
180
List the available versions of go-ipfs:
181
+
182
```
183
$ ipfs cat /ipns/dist.ipfs.io/go-ipfs/versions
184
```
185
186
Then, to view available builds for a version from the previous command ($VERSION):
187
+
188
```
189
$ ipfs ls /ipns/dist.ipfs.io/go-ipfs/$VERSION
190
```
191
192
To download a given build of a version:
193
+
194
```
195
$ ipfs get /ipns/dist.ipfs.io/go-ipfs/$VERSION/go-ipfs_$VERSION_darwin-386.tar.gz # darwin 32-bit build
196
$ ipfs get /ipns/dist.ipfs.io/go-ipfs/$VERSION/go-ipfs_$VERSION_darwin-amd64.tar.gz # darwin 64-bit build
@@ -317,41 +318,72 @@ Stop the running container:
318
319
### Troubleshooting
320
320
-If you have previously installed IPFS before and you are running into
321
-problems getting a newer version to work, try deleting (or backing up somewhere
322
-else) your IPFS config directory (~/.ipfs by default) and rerunning `ipfs init`.
323
-This will reinitialize the config file to its defaults and clear out the local
324
-datastore of any bad entries.
321
+If you have previously installed IPFS before and you are running into problems getting a newer version to work, try deleting (or backing up somewhere else) your IPFS config directory (~/.ipfs by default) and rerunning `ipfs init`. This will reinitialize the config file to its defaults and clear out the local datastore of any bad entries.
322
326
-Please direct general questions and help requests to our
327
-[forum](https://discuss.ipfs.io) or our IRC channel (freenode #ipfs).
323
+Please direct general questions and help requests to our [forum](https://discuss.ipfs.io) or our IRC channel (freenode #ipfs).
324
329
-If you believe you've found a bug, check the [issues list](https://github.com/ipfs/go-ipfs/issues)
330
-and, if you don't see your problem there, either come talk to us on IRC (freenode #ipfs) or
331
-file an issue of your own!
325
+If you believe you've found a bug, check the [issues list](https://github.com/ipfs/go-ipfs/issues) and, if you don't see your problem there, either come talk to us on IRC (freenode #ipfs) or file an issue of your own!
326
333
-## Contributing
327
+## Development
328
335
-We ❤️ all [our contributors](docs/AUTHORS); this project wouldn’t be what it is without you! If you want to help out, please see [Contribute.md](contribute.md).
329
+This is a simple description of where the codebase stands. There are multiple subpackages:
330
337
-This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
331
+- `bitswap` - the block exchange
332
+- `blocks` - handles dealing with individual blocks and sharding files
333
+- `blockservice` - handles getting and storing blocks
334
+- `cmd/ipfs` - cli ipfs tool - the main **entrypoint** atm
335
+- `config` - load/edit configuration
336
+- `core` - the core node, joins all the pieces
337
+- `fuse/readonly` - mount `/ipfs` as a readonly fuse fs
338
+- `importer` - import files into ipfs
339
+- `merkledag` - merkle dag data structure
340
+- `path` - path resolution over merkledag data structure
341
+- `peer` - identity + addresses of local and remote peers
342
+- `routing` - the routing system
343
+- `routing/dht` - the DHT default routing system implementation
344
+- `swarm` - connection multiplexing, many peers and many transports
345
+- `util` - various utilities
346
339
-### Want to hack on IPFS?
347
+Some places to get you started on the codebase:
348
341
-[](https://github.com/ipfs/community/blob/master/contributing.md)
349
+- Main file: [cmd/ipfs/main.go](https://github.com/ipfs/go-ipfs/blob/master/cmd/ipfs/main.go)
350
+- CLI Commands: [core/commands/](https://github.com/ipfs/go-ipfs/tree/master/core/commands)
351
+- Bitswap (the data trading engine): [exchange/bitswap/](https://github.com/ipfs/go-ipfs/tree/master/exchange/bitswap)
352
+- libp2p
353
+ - libp2p: https://github.com/libp2p/go-libp2p
354
+ - DHT: https://github.com/libp2p/go-libp2p-kad-dht
355
+ - PubSub: https://github.com/libp2p/go-floodsub
356
+
357
+### CLI, HTTP-API, Architecture Diagram
358
343
-### Want to read our code?
359
+
360
345
-Some places to get you started. (WIP)
361
+> [Origin](https://github.com/ipfs/pm/pull/678#discussion_r210410924)
362
347
-Main file: [cmd/ipfs/main.go](https://github.com/ipfs/go-ipfs/blob/master/cmd/ipfs/main.go) <br>
348
-CLI Commands: [core/commands/](https://github.com/ipfs/go-ipfs/tree/master/core/commands) <br>
349
-Bitswap (the data trading engine): [exchange/bitswap/](https://github.com/ipfs/go-ipfs/tree/master/exchange/bitswap)
363
+Description: Dotted means "likely going away". The "Legacy" parts are thin wrappers around some commands to translate between the new system and the old system. The grayed-out parts on the "daemon" diagram are there to show that the code is all the same, it's just that we turn some pieces on and some pieces off depending on whether we're running on the client or the server.
364
351
-DHT: https://github.com/libp2p/go-libp2p-kad-dht <br>
352
-PubSub: https://github.com/libp2p/go-floodsub <br>
353
-libp2p: https://github.com/libp2p/go-libp2p
365
+### Testing
366
+
367
+```
368
+make test
369
+```
370
+
371
+### Development Dependencies
372
+
373
+If you make changes to the protocol buffers, you will need to install the [protoc compiler](https://github.com/google/protobuf).
374
+
375
+### Developer Notes
376
+
377
+Find more documentation for developers on [docs](./docs)
378
+
379
+## Contributing
380
+
381
+[](https://github.com/ipfs/community/blob/master/contributing.md)
382
+
383
+We ❤️ all [our contributors](docs/AUTHORS); this project wouldn’t be what it is without you! If you want to help out, please see [Contribute.md](contribute.md).
384
+
385
+This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
386
387
## License
388
357
-MIT
389
+[MIT](./LICENSE)
dev.md
deleted
-62
@@ -1,62 +0,0 @@
1
-# go-ipfs development
2
-
3
-This is a simple description of where the codebase stands.
4
-
5
-There are multiple subpackages:
6
-
7
-- `bitswap` - the block exchange
8
-- `blocks` - handles dealing with individual blocks and sharding files
9
-- `blockservice` - handles getting and storing blocks
10
-- `cmd/ipfs` - cli ipfs tool - the main **entrypoint** atm
11
-- `config` - load/edit configuration
12
-- `core` - the core node, joins all the pieces
13
-- `fuse/readonly` - mount `/ipfs` as a readonly fuse fs
14
-- `importer` - import files into ipfs
15
-- `merkledag` - merkle dag data structure
16
-- `path` - path resolution over merkledag data structure
17
-- `peer` - identity + addresses of local and remote peers
18
-- `routing` - the routing system
19
-- `routing/dht` - the DHT default routing system implementation
20
-- `swarm` - connection multiplexing, many peers and many transports
21
-- `util` - various utilities
22
-
23
-
24
-### What's done:
25
-
26
-- merkle dag data structure
27
-- path resolution over merkle dag
28
-- local storage of blocks
29
-- basic file import/export (`ipfs add`, `ipfs cat`)
30
-- mounting `/ipfs` (try `{cat, ls} /ipfs/<path>`)
31
-- multiplexing connections (tcp atm)
32
-- peer addressing
33
-- dht - impl basic kademlia routing
34
-- bitswap - impl basic block exchange functionality
35
-- crypto - building trust between peers in the network
36
-- block splitting on import - Rabin fingerprints, etc
37
-
38
-### What's in progress:
39
-
40
-- ipns - impl `/ipns` obj publishing + path resolution
41
-- expose objects to the web at `http://ipfs.io/<path>`
42
-
43
-
44
-### What's next:
45
-
46
-- version control - `commit` like data structure
47
-- more...
48
-
49
-## Cool demos
50
-
51
-A list of cool demos to work towards
52
-
53
-- boot a VM from an image in ipfs
54
-- boot a VM from a filesystem tree in ipfs
55
-- publish static websites directly from ipfs
56
-- expose objects to the web at `http://ipfs.io/<path>`
57
-- mounted auto-committing versioned personal dropbox
58
-- mounted encrypted personal/group dropbox
59
-- mounted {npm, apt, other pkg manager} registry
60
-- open a video on ipfs, stream it in
61
-- watch a video with a topology of 1 seed N leechers (N ~100)
62
-- more in section 3.8 in the [paper](https://github.com/ipfs/ipfs/blob/master/papers/ipfs-cap2pfs/ipfs-p2p-file-system.pdf)
docs/cli-http-api-core-diagram.png
Binary files /dev/null and b/docs/cli-http-api-core-diagram.png differ