add more buttons; remove some sections covered in the docs; general cleanup
- added dynamic buttons for packages/downloads which shows the latest version where possible - dynamic next milestone buttons - reordered to have package managers and docker on top, manual downloads afterwards - remove the docker and the cli section, since they are covered equally in the docs + button links - added more sections to the navigation, to find stuff easier - dynamic go requirement version button - some social media buttons - general cleanup (cherry picked from commit 04d1369a6314557f573a461e9d42d646e773d9a2)
@RubenKelevra committed
Jul 18, 2021 at 23:04 UTC
63213c3e58cb9fa5b9e47499178b1a03e56647c9
1 file changed
+107
-188
README.md
+107
-188
@@ -2,9 +2,9 @@
2
3
4
5
-[](https://protocol.ai)
6
-[](https://godoc.org/github.com/ipfs/go-ipfs)
7
-[](https://circleci.com/gh/ipfs/go-ipfs)
5
+[](https://protocol.ai)
6
+[](https://godoc.org/github.com/ipfs/go-ipfs)
7
+[](https://circleci.com/gh/ipfs/go-ipfs)
8
9
## What is IPFS?
10
@@ -19,31 +19,59 @@ Before opening an issue, consider using one of the following locations to ensure
19
- Exploration of new ideas in [ipfs/notes issues](https://github.com/ipfs/notes/issues).
20
- Ask questions and meet the rest of the community at the [IPFS Forum](https://discuss.ipfs.io).
21
- Or [chat with us](https://docs.ipfs.io/community/chat/).
22
+
23
+[](https://www.youtube.com/channel/UCdjsUXJ3QawK4O5L1kqqsew) [](https://twitter.com/IPFS)
24
+
25
+## Next milestones
26
+
27
+[Milestones on Github](https://github.com/ipfs/go-ipfs/milestones)
28
+
29
+<!-- ToDo automate creation of these
30
+[](https://github.com/ipfs/go-ipfs/milestone/51)
31
+[](https://github.com/ipfs/go-ipfs/milestone/48)
32
+[](https://github.com/ipfs/go-ipfs/milestone/50)
33
+[](https://github.com/ipfs/go-ipfs/milestone/49)
34
+-->
35
36
## Table of Contents
37
38
- [Security Issues](#security-issues)
39
- [Install](#install)
40
- [System Requirements](#system-requirements)
28
- - [Install prebuilt packages](#install-prebuilt-packages)
29
- - [From Linux package managers](#from-linux-package-managers)
30
- - [From Windows package managers](#from-windows-package-managers)
31
- - [From macOS package managers](#from-macos-package-managers)
41
+ - [Docker](#docker)
42
+ - [Native Linux package managers](#native-linux-package-managers)
43
+ - [ArchLinux](#archlinux)
44
+ - [Nix](#nix-linux)
45
+ - [Solus](#solus)
46
+ - [openSUSE](#opensuse)
47
+ - [Other package managers](#other-package-managers)
48
+ - [Guix](#guix)
49
+ - [Snap](#snap)
50
+ - [macOS package managers](#macos-package-managers)
51
+ - [MacPorts](#MacPorts)
52
+ - [Nix](#nix-macos)
53
+ - [Windows package managers](#windows-package-managers)
54
+ - [Chocolatey](#chocolatey)
55
+ - [Scoop](#scoop)
56
+ - [Install prebuilt binaries](#install-prebuilt-binaries)
57
- [Build from Source](#build-from-source)
58
- [Install Go](#install-go)
59
- [Download and Compile IPFS](#download-and-compile-ipfs)
60
+ - [Cross Compiling](#cross-compiling)
61
+ - [OpenSSL](#openssl)
62
- [Troubleshooting](#troubleshooting)
63
- [Updating go-ipfs](#updating-go-ipfs)
64
- [Getting Started](#getting-started)
65
- [Some things to try](#some-things-to-try)
66
- [Usage](#usage)
40
- - [Running IPFS inside Docker](#running-ipfs-inside-docker)
67
- [Troubleshooting](#troubleshooting-1)
68
- [Packages](#packages)
69
- [Development](#development)
70
+ - [Map of go-ipfs Subsystems](#map-of-go-ipfs-subsystems)
71
- [CLI, HTTP-API, Architecture Diagram](#cli-http-api-architecture-diagram)
72
- [Testing](#testing)
73
- [Development Dependencies](#development-dependencies)
74
+ - [Developer Notes](#developer-notes)
75
- [Contributing](#contributing)
76
- [License](#license)
77
@@ -68,40 +96,32 @@ If your system is resource-constrained, we recommend:
96
1. Installing OpenSSL and rebuilding go-ipfs manually with `make build GOTAGS=openssl`. See the [download and compile](#download-and-compile-ipfs) section for more information on compiling go-ipfs.
97
2. Initializing your daemon with `ipfs init --profile=lowpower`
98
71
-### Install prebuilt packages
72
-
73
-We host prebuilt binaries over at our [distributions page](https://ipfs.io/ipns/dist.ipfs.io#go-ipfs).
99
+### Docker
100
75
-From there:
76
-- Click the blue "Download go-ipfs" on the right side of the page.
77
-- Open/extract the archive.
78
-- Move `ipfs` to your path (`install.sh` can do it for you).
101
+[](https://hub.docker.com/r/ipfs/go-ipfs/)
102
80
-You can also download go-ipfs from this project's GitHub releases page if you are unable to access ipfs.io.
103
+More info on how to run go-ipfs inside docker can be found [here](https://docs.ipfs.io/how-to/run-ipfs-inside-docker/).
104
82
-### From Linux package managers
105
+### Native Linux package managers
106
107
- [Arch Linux](#arch-linux)
108
- [Nix](#nix-linux)
109
- [Solus](#solus)
87
-- [Snap](#snap)
110
+- [openSUSE](#openSUSE)
111
89
-#### Arch Linux
112
+#### ArchLinux
113
91
-In Arch Linux go-ipfs is available as
92
-[go-ipfs](https://www.archlinux.org/packages/community/x86_64/go-ipfs/) package.
114
+[](https://wiki.archlinux.org/title/IPFS)
115
94
-```
95
-$ sudo pacman -S go-ipfs
116
+```bash
117
+# pacman -Syu go-ipfs
118
```
119
98
-Development version of go-ipfs is also on AUR under
99
-[go-ipfs-git](https://aur.archlinux.org/packages/go-ipfs-git/).
100
-You can install it using your favorite AUR Helper or manually from AUR.
120
+[](https://aur.archlinux.org/packages/go-ipfs-git/)
121
122
#### <a name="nix-linux">Nix</a>
123
104
-For Linux and macOS you can use the purely functional package manager [Nix](https://nixos.org/nix/):
124
+With the purely functional package manager [Nix](https://nixos.org/nix/) you can install go-ipfs like this:
125
126
```
127
$ nix-env -i ipfs
@@ -109,14 +129,6 @@ $ nix-env -i ipfs
129
130
You can also install the Package by using its attribute name, which is also `ipfs`.
131
112
-#### Guix
113
-
114
-GNU's functional package manager, [Guix](https://www.gnu.org/software/guix/), also provides a go-ipfs package:
115
-
116
-```
117
-$ guix package -i go-ipfs
118
-```
119
-
132
#### Solus
133
134
In solus, go-ipfs is available in the main repository as
@@ -128,36 +140,32 @@ $ sudo eopkg install go-ipfs
140
141
You can also install it through the Solus software center.
142
131
-#### Snap
132
-
133
-With snap, in any of the [supported Linux distributions](https://snapcraft.io/docs/core/install):
143
+#### openSUSE
144
135
-```
136
-$ sudo snap install ipfs
137
-```
145
+[Community Package for go-ipfs](https://software.opensuse.org/package/go-ipfs)
146
139
-### From Windows package managers
147
+### Other package managers
148
141
-- [Chocolatey](#chocolatey)
142
-- [Scoop](#scoop)
149
+- [Guix](#guix)
150
+- [Snap](#snap)
151
144
-#### Chocolatey
152
+#### Guix
153
146
-The package name is [go-ipfs](https://chocolatey.org/packages/go-ipfs):
154
+GNU's functional package manager, [Guix](https://www.gnu.org/software/guix/), also provides a go-ipfs package:
155
148
-```Powershell
149
-PS> choco install go-ipfs
156
+```
157
+$ guix package -i go-ipfs
158
```
159
152
-#### Scoop
160
+#### Snap
161
+
162
+With snap, in any of the [supported Linux distributions](https://snapcraft.io/docs/core/install):
163
154
-Scoop provides `go-ipfs` in its 'extras' bucket.
155
-```Powershell
156
-PS> scoop bucket add extras
157
-PS> scoop install go-ipfs
164
+```
165
+$ sudo snap install ipfs
166
```
167
160
-### From macOS package managers
168
+#### macOS package managers
169
170
- [MacPorts](#macports)
171
- [Nix](#nix-macos)
@@ -172,7 +180,7 @@ $ sudo port install ipfs
180
181
#### <a name="nix-macos">Nix</a>
182
175
-For macOS and Linux you can use the purely functional package manager [Nix](https://nixos.org/nix/):
183
+In macOS you can use the purely functional package manager [Nix](https://nixos.org/nix/):
184
185
```
186
$ nix-env -i ipfs
@@ -180,9 +188,45 @@ $ nix-env -i ipfs
188
189
You can also install the Package by using its attribute name, which is also `ipfs`.
190
191
+### Windows package managers
192
+
193
+- [Chocolatey](#chocolatey)
194
+- [Scoop](#scoop)
195
+
196
+#### Chocolatey
197
+
198
+[](https://chocolatey.org/packages/go-ipfs)
199
+
200
+```Powershell
201
+PS> choco install ipfs
202
+```
203
+
204
+#### Scoop
205
+
206
+Scoop provides `go-ipfs` in its 'extras' bucket.
207
+```Powershell
208
+PS> scoop bucket add extras
209
+PS> scoop install go-ipfs
210
+```
211
+
212
+### Install prebuilt binaries
213
+
214
+[](https://ipfs.io/ipns/dist.ipfs.io#go-ipfs)
215
+
216
+From there:
217
+- Click the blue "Download go-ipfs" on the right side of the page.
218
+- Open/extract the archive.
219
+- Move `ipfs` to your path (`install.sh` can do it for you).
220
+
221
+You can also download go-ipfs from this project's GitHub releases page if you are unable to access [dist.ipfs.io](https://ipfs.io/ipns/dist.ipfs.io#go-ipfs):
222
+
223
+[GitHub releases](https://github.com/ipfs/go-ipfs/releases)
224
+
225
### Build from Source
226
185
-go-ipfs's build system requires Go 1.15.2 and some standard POSIX build tools:
227
+
228
+
229
+go-ipfs's build system requires Go and some standard POSIX build tools:
230
231
* GNU make
232
* Git
@@ -192,7 +236,9 @@ To build without GCC, build with `CGO_ENABLED=0` (e.g., `make build CGO_ENABLED=
236
237
#### Install Go
238
195
-The build process for ipfs requires Go 1.15.2 or higher. If you don't have it: [Download Go 1.15+](https://golang.org/dl/).
239
+
240
+
241
+If you need to update: [Download latest version of Go](https://golang.org/dl/).
242
243
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`:
244
@@ -284,7 +330,10 @@ $ ipfs get /ipns/dist.ipfs.io/go-ipfs/$VERSION/go-ipfs_$VERSION_windows-amd64.zi
330
331
## Getting Started
332
287
-See also: https://docs.ipfs.io/introduction/usage/
333
+### Usage
334
+
335
+[](https://docs.ipfs.io/how-to/command-line-quick-start/)
336
+[](https://docs.ipfs.io/reference/cli/)
337
338
To start using IPFS, you must first initialize IPFS's config files on your
339
system, this is done with `ipfs init`. See `ipfs init --help` for information on
@@ -301,136 +350,6 @@ Basic proof of 'ipfs working' locally:
350
# QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o
351
ipfs cat <that hash>
352
304
-### Usage
305
-
306
-```
307
- ipfs - Global p2p merkle-dag filesystem.
308
-
309
- ipfs [<flags>] <command> [<arg>] ...
310
-
311
-SUBCOMMANDS
312
- BASIC COMMANDS
313
- init Initialize local IPFS configuration
314
- add <path> Add a file to IPFS
315
- cat <ref> Show IPFS object data
316
- get <ref> Download IPFS objects
317
- ls <ref> List links from an object
318
- refs <ref> List hashes of links from an object
319
-
320
- DATA STRUCTURE COMMANDS
321
- dag Interact with IPLD DAG nodes
322
- files Interact with files as if they were a unix filesystem
323
- block Interact with raw blocks in the datastore
324
-
325
- ADVANCED COMMANDS
326
- daemon Start a long-running daemon process
327
- mount Mount an IPFS read-only mount point
328
- resolve Resolve any type of name
329
- name Publish and resolve IPNS names
330
- key Create and list IPNS name keypairs
331
- dns Resolve DNS links
332
- pin Pin objects to local storage
333
- repo Manipulate the IPFS repository
334
- stats Various operational stats
335
- p2p Libp2p stream mounting
336
- filestore Manage the filestore (experimental)
337
-
338
- NETWORK COMMANDS
339
- id Show info about IPFS peers
340
- bootstrap Add or remove bootstrap peers
341
- swarm Manage connections to the p2p network
342
- dht Query the DHT for values or peers
343
- ping Measure the latency of a connection
344
- diag Print diagnostics
345
-
346
- TOOL COMMANDS
347
- config Manage configuration
348
- version Show IPFS version information
349
- update Download and apply go-ipfs updates
350
- commands List all available commands
351
- cid Convert and discover properties of CIDs
352
- log Manage and show logs of running daemon
353
-
354
- Use 'ipfs <command> --help' to learn more about each command.
355
-
356
- ipfs uses a repository in the local file system. By default, the repo is located at
357
- ~/.ipfs. To change the repo location, set the $IPFS_PATH environment variable:
358
-
359
- export IPFS_PATH=/path/to/ipfsrepo
360
-```
361
-
362
-### Running IPFS inside Docker
363
-
364
-An IPFS docker image is hosted at [hub.docker.com/r/ipfs/go-ipfs](https://hub.docker.com/r/ipfs/go-ipfs/).
365
-To make files visible inside the container you need to mount a host directory
366
-with the `-v` option to docker. Choose a directory that you want to use to
367
-import/export files from IPFS. You should also choose a directory to store
368
-IPFS files that will persist when you restart the container.
369
-
370
- export ipfs_staging=</absolute/path/to/somewhere/>
371
- export ipfs_data=</absolute/path/to/somewhere_else/>
372
-
373
-Start a container running ipfs and expose ports 4001, 5001 and 8080:
374
-
375
- docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest
376
-
377
-Watch the ipfs log:
378
-
379
- docker logs -f ipfs_host
380
-
381
-Wait for ipfs to start. ipfs is running when you see:
382
-
383
- Gateway (readonly) server
384
- listening on /ip4/0.0.0.0/tcp/8080
385
-
386
-You can now stop watching the log.
387
-
388
-Run ipfs commands:
389
-
390
- docker exec ipfs_host ipfs <args...>
391
-
392
-For example: connect to peers
393
-
394
- docker exec ipfs_host ipfs swarm peers
395
-
396
-Add files:
397
-
398
- cp -r <something> $ipfs_staging
399
- docker exec ipfs_host ipfs add -r /export/<something>
400
-
401
-Stop the running container:
402
-
403
- docker stop ipfs_host
404
-
405
-When starting a container running ipfs for the first time with an empty data directory, it will call `ipfs init` to initialize configuration files and generate a new keypair. At this time, you can choose which profile to apply using the `IPFS_PROFILE` environment variable:
406
-
407
- docker run -d --name ipfs_host -e IPFS_PROFILE=server -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest
408
-
409
-#### Private swarms inside Docker
410
-
411
-It is possible to initialize the container with a swarm key file (`/data/ipfs/swarm.key`) using the variables `IPFS_SWARM_KEY` and `IPFS_SWARM_KEY_FILE`. The `IPFS_SWARM_KEY` creates `swarm.key` with the contents of the variable itself, whilst `IPFS_SWARM_KEY_FILE` copies the key from a path stored in the variable. The `IPFS_SWARM_KEY_FILE` **overwrites** the key generated by `IPFS_SWARM_KEY`.
412
-
413
- docker run -d --name ipfs_host -e IPFS_SWARM_KEY=<your swarm key> -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest
414
-
415
-The swarm key initialization can also be done using docker secrets **(requires docker swarm or docker-compose)**:
416
-
417
- cat your_swarm.key | docker secret create swarm_key_secret -
418
- docker run -d --name ipfs_host --secret swarm_key_secret -e IPFS_SWARM_KEY_FILE=/run/secrets/swarm_key_secret -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest
419
-
420
-#### Key rotation inside Docker
421
-
422
-If needed, it is possible to do key rotation in an ephemeral container that is temporarily executing against a volume that is mounted under `/data/ipfs`:
423
-
424
-```sh
425
-# given container named 'ipfs-test' that persists repo at /path/to/persisted/.ipfs
426
-$ docker run -d --name ipfs-test -v /path/to/persisted/.ipfs:/data/ipfs ipfs/go-ipfs:v0.7.0
427
-$ docker stop ipfs-test
428
-
429
-# key rotation works like this (old key saved under 'old-self')
430
-$ docker run --rm -it -v /path/to/persisted/.ipfs:/data/ipfs ipfs/go-ipfs:v0.7.0 key rotate -o old-self -t ed25519
431
-$ docker start ipfs-test # will start with the new key
432
-```
433
-
353
### Troubleshooting
354
355
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.