diff --git a/README.md b/README.md
index 4486e06893f..753a911a09b 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@
![banner](https://ipfs.io/ipfs/bafykbzacecaesuqmivkauix25v6i6xxxsvsrtxknhgb5zak3xxsg2nb4dhs2u/ipfs.go.png)
-[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai)
-[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=flat-square)](https://godoc.org/github.com/ipfs/go-ipfs)
-[![CircleCI](https://img.shields.io/circleci/build/github/ipfs/go-ipfs?style=flat-square)](https://circleci.com/gh/ipfs/go-ipfs)
+[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square&cacheSeconds=3600)](https://protocol.ai)
+[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=flat-square&cacheSeconds=3600)](https://godoc.org/github.com/ipfs/go-ipfs)
+[![CircleCI](https://img.shields.io/circleci/build/github/ipfs/go-ipfs?style=flat-square&cacheSeconds=3600)](https://circleci.com/gh/ipfs/go-ipfs)
## What is IPFS?
@@ -19,31 +19,59 @@ Before opening an issue, consider using one of the following locations to ensure
- Exploration of new ideas in [ipfs/notes issues](https://github.com/ipfs/notes/issues).
- Ask questions and meet the rest of the community at the [IPFS Forum](https://discuss.ipfs.io).
- Or [chat with us](https://docs.ipfs.io/community/chat/).
+
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UCdjsUXJ3QawK4O5L1kqqsew?label=Subscribe%20IPFS&style=social&cacheSeconds=3600)](https://www.youtube.com/channel/UCdjsUXJ3QawK4O5L1kqqsew) [![Follow @IPFS on Twitter](https://img.shields.io/twitter/follow/IPFS?style=social&cacheSeconds=3600)](https://twitter.com/IPFS)
+
+## Next milestones
+
+[Milestones on Github](https://github.com/ipfs/go-ipfs/milestones)
+
+
## Table of Contents
- [Security Issues](#security-issues)
- [Install](#install)
- [System Requirements](#system-requirements)
- - [Install prebuilt packages](#install-prebuilt-packages)
- - [From Linux package managers](#from-linux-package-managers)
- - [From Windows package managers](#from-windows-package-managers)
- - [From macOS package managers](#from-macos-package-managers)
+ - [Docker](#docker)
+ - [Native Linux package managers](#native-linux-package-managers)
+ - [ArchLinux](#archlinux)
+ - [Nix](#nix-linux)
+ - [Solus](#solus)
+ - [openSUSE](#opensuse)
+ - [Other package managers](#other-package-managers)
+ - [Guix](#guix)
+ - [Snap](#snap)
+ - [macOS package managers](#macos-package-managers)
+ - [MacPorts](#MacPorts)
+ - [Nix](#nix-macos)
+ - [Windows package managers](#windows-package-managers)
+ - [Chocolatey](#chocolatey)
+ - [Scoop](#scoop)
+ - [Install prebuilt binaries](#install-prebuilt-binaries)
- [Build from Source](#build-from-source)
- [Install Go](#install-go)
- [Download and Compile IPFS](#download-and-compile-ipfs)
+ - [Cross Compiling](#cross-compiling)
+ - [OpenSSL](#openssl)
- [Troubleshooting](#troubleshooting)
- [Updating go-ipfs](#updating-go-ipfs)
- [Getting Started](#getting-started)
- [Some things to try](#some-things-to-try)
- [Usage](#usage)
- - [Running IPFS inside Docker](#running-ipfs-inside-docker)
- [Troubleshooting](#troubleshooting-1)
- [Packages](#packages)
- [Development](#development)
+ - [Map of go-ipfs Subsystems](#map-of-go-ipfs-subsystems)
- [CLI, HTTP-API, Architecture Diagram](#cli-http-api-architecture-diagram)
- [Testing](#testing)
- [Development Dependencies](#development-dependencies)
+ - [Developer Notes](#developer-notes)
- [Contributing](#contributing)
- [License](#license)
@@ -68,40 +96,32 @@ If your system is resource-constrained, we recommend:
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.
2. Initializing your daemon with `ipfs init --profile=lowpower`
-### Install prebuilt packages
-
-We host prebuilt binaries over at our [distributions page](https://ipfs.io/ipns/dist.ipfs.io#go-ipfs).
+### Docker
-From there:
-- Click the blue "Download go-ipfs" on the right side of the page.
-- Open/extract the archive.
-- Move `ipfs` to your path (`install.sh` can do it for you).
+[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/ipfs/go-ipfs?color=blue&label=go-ipfs%20docker%20image&logo=docker&sort=semver&style=flat-square&cacheSeconds=3600)](https://hub.docker.com/r/ipfs/go-ipfs/)
-You can also download go-ipfs from this project's GitHub releases page if you are unable to access ipfs.io.
+More info on how to run go-ipfs inside docker can be found [here](https://docs.ipfs.io/how-to/run-ipfs-inside-docker/).
-### From Linux package managers
+### Native Linux package managers
- [Arch Linux](#arch-linux)
- [Nix](#nix-linux)
- [Solus](#solus)
-- [Snap](#snap)
+- [openSUSE](#openSUSE)
-#### Arch Linux
+#### ArchLinux
-In Arch Linux go-ipfs is available as
-[go-ipfs](https://www.archlinux.org/packages/community/x86_64/go-ipfs/) package.
+[![go-ipfs via Community Repo](https://img.shields.io/archlinux/v/community/x86_64/go-ipfs?color=1793d1&label=go-ipfs&logo=arch-linux&style=flat-square&cacheSeconds=3600)](https://wiki.archlinux.org/title/IPFS)
-```
-$ sudo pacman -S go-ipfs
+```bash
+# pacman -Syu go-ipfs
```
-Development version of go-ipfs is also on AUR under
-[go-ipfs-git](https://aur.archlinux.org/packages/go-ipfs-git/).
-You can install it using your favorite AUR Helper or manually from AUR.
+[![go-ipfs-git via AUR](https://img.shields.io/static/v1?label=go-ipfs-git&message=latest%40master&color=1793d1&logo=arch-linux&style=flat-square&cacheSeconds=3600)](https://aur.archlinux.org/packages/go-ipfs-git/)
#### Nix
-For Linux and macOS you can use the purely functional package manager [Nix](https://nixos.org/nix/):
+With the purely functional package manager [Nix](https://nixos.org/nix/) you can install go-ipfs like this:
```
$ nix-env -i ipfs
@@ -109,14 +129,6 @@ $ nix-env -i ipfs
You can also install the Package by using its attribute name, which is also `ipfs`.
-#### Guix
-
-GNU's functional package manager, [Guix](https://www.gnu.org/software/guix/), also provides a go-ipfs package:
-
-```
-$ guix package -i go-ipfs
-```
-
#### Solus
In solus, go-ipfs is available in the main repository as
@@ -128,36 +140,32 @@ $ sudo eopkg install go-ipfs
You can also install it through the Solus software center.
-#### Snap
-
-With snap, in any of the [supported Linux distributions](https://snapcraft.io/docs/core/install):
+#### openSUSE
-```
-$ sudo snap install ipfs
-```
+[Community Package for go-ipfs](https://software.opensuse.org/package/go-ipfs)
-### From Windows package managers
+### Other package managers
-- [Chocolatey](#chocolatey)
-- [Scoop](#scoop)
+- [Guix](#guix)
+- [Snap](#snap)
-#### Chocolatey
+#### Guix
-The package name is [go-ipfs](https://chocolatey.org/packages/go-ipfs):
+GNU's functional package manager, [Guix](https://www.gnu.org/software/guix/), also provides a go-ipfs package:
-```Powershell
-PS> choco install go-ipfs
+```
+$ guix package -i go-ipfs
```
-#### Scoop
+#### Snap
+
+With snap, in any of the [supported Linux distributions](https://snapcraft.io/docs/core/install):
-Scoop provides `go-ipfs` in its 'extras' bucket.
-```Powershell
-PS> scoop bucket add extras
-PS> scoop install go-ipfs
+```
+$ sudo snap install ipfs
```
-### From macOS package managers
+#### macOS package managers
- [MacPorts](#macports)
- [Nix](#nix-macos)
@@ -172,7 +180,7 @@ $ sudo port install ipfs
#### Nix
-For macOS and Linux you can use the purely functional package manager [Nix](https://nixos.org/nix/):
+In macOS you can use the purely functional package manager [Nix](https://nixos.org/nix/):
```
$ nix-env -i ipfs
@@ -180,9 +188,45 @@ $ nix-env -i ipfs
You can also install the Package by using its attribute name, which is also `ipfs`.
+### Windows package managers
+
+- [Chocolatey](#chocolatey)
+- [Scoop](#scoop)
+
+#### Chocolatey
+
+[![Chocolatey Version](https://img.shields.io/chocolatey/v/go-ipfs?color=00a4ef&label=go-ipfs&logo=windows&style=flat-square&cacheSeconds=3600)](https://chocolatey.org/packages/go-ipfs)
+
+```Powershell
+PS> choco install ipfs
+```
+
+#### Scoop
+
+Scoop provides `go-ipfs` in its 'extras' bucket.
+```Powershell
+PS> scoop bucket add extras
+PS> scoop install go-ipfs
+```
+
+### Install prebuilt binaries
+
+[![dist.ipfs.io Downloads](https://img.shields.io/github/v/release/ipfs/go-ipfs?label=dist.ipfs.io&logo=ipfs&style=flat-square&cacheSeconds=3600)](https://ipfs.io/ipns/dist.ipfs.io#go-ipfs)
+
+From there:
+- Click the blue "Download go-ipfs" on the right side of the page.
+- Open/extract the archive.
+- Move `ipfs` to your path (`install.sh` can do it for you).
+
+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):
+
+[GitHub releases](https://github.com/ipfs/go-ipfs/releases)
+
### Build from Source
-go-ipfs's build system requires Go 1.15.2 and some standard POSIX build tools:
+![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/ipfs/go-ipfs?label=Requires%20Go&logo=go&style=flat-square&cacheSeconds=3600)
+
+go-ipfs's build system requires Go and some standard POSIX build tools:
* GNU make
* Git
@@ -192,7 +236,9 @@ To build without GCC, build with `CGO_ENABLED=0` (e.g., `make build CGO_ENABLED=
#### Install Go
-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/).
+![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/ipfs/go-ipfs?label=Requires%20Go&logo=go&style=flat-square&cacheSeconds=3600)
+
+If you need to update: [Download latest version of Go](https://golang.org/dl/).
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`:
@@ -284,7 +330,10 @@ $ ipfs get /ipns/dist.ipfs.io/go-ipfs/$VERSION/go-ipfs_$VERSION_windows-amd64.zi
## Getting Started
-See also: https://docs.ipfs.io/introduction/usage/
+### Usage
+
+[![docs: Command-line quick start](https://img.shields.io/static/v1?label=docs&message=Command-line%20quick%20start&color=blue&style=flat-square&cacheSeconds=3600)](https://docs.ipfs.io/how-to/command-line-quick-start/)
+[![docs: Command-line reference](https://img.shields.io/static/v1?label=docs&message=Command-line%20reference&color=blue&style=flat-square&cacheSeconds=3600)](https://docs.ipfs.io/reference/cli/)
To start using IPFS, you must first initialize IPFS's config files on your
system, this is done with `ipfs init`. See `ipfs init --help` for information on
@@ -301,136 +350,6 @@ Basic proof of 'ipfs working' locally:
# QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o
ipfs cat
-### Usage
-
-```
- ipfs - Global p2p merkle-dag filesystem.
-
- ipfs [] [] ...
-
-SUBCOMMANDS
- BASIC COMMANDS
- init Initialize local IPFS configuration
- add Add a file to IPFS
- cat [ Show IPFS object data
- get ][ Download IPFS objects
- ls ][ List links from an object
- refs ][ List hashes of links from an object
-
- DATA STRUCTURE COMMANDS
- dag Interact with IPLD DAG nodes
- files Interact with files as if they were a unix filesystem
- block Interact with raw blocks in the datastore
-
- ADVANCED COMMANDS
- daemon Start a long-running daemon process
- mount Mount an IPFS read-only mount point
- resolve Resolve any type of name
- name Publish and resolve IPNS names
- key Create and list IPNS name keypairs
- dns Resolve DNS links
- pin Pin objects to local storage
- repo Manipulate the IPFS repository
- stats Various operational stats
- p2p Libp2p stream mounting
- filestore Manage the filestore (experimental)
-
- NETWORK COMMANDS
- id Show info about IPFS peers
- bootstrap Add or remove bootstrap peers
- swarm Manage connections to the p2p network
- dht Query the DHT for values or peers
- ping Measure the latency of a connection
- diag Print diagnostics
-
- TOOL COMMANDS
- config Manage configuration
- version Show IPFS version information
- update Download and apply go-ipfs updates
- commands List all available commands
- cid Convert and discover properties of CIDs
- log Manage and show logs of running daemon
-
- Use 'ipfs --help' to learn more about each command.
-
- ipfs uses a repository in the local file system. By default, the repo is located at
- ~/.ipfs. To change the repo location, set the $IPFS_PATH environment variable:
-
- export IPFS_PATH=/path/to/ipfsrepo
-```
-
-### Running IPFS inside Docker
-
-An IPFS docker image is hosted at [hub.docker.com/r/ipfs/go-ipfs](https://hub.docker.com/r/ipfs/go-ipfs/).
-To make files visible inside the container you need to mount a host directory
-with the `-v` option to docker. Choose a directory that you want to use to
-import/export files from IPFS. You should also choose a directory to store
-IPFS files that will persist when you restart the container.
-
- export ipfs_staging=
- export ipfs_data=
-
-Start a container running ipfs and expose ports 4001, 5001 and 8080:
-
- 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
-
-Watch the ipfs log:
-
- docker logs -f ipfs_host
-
-Wait for ipfs to start. ipfs is running when you see:
-
- Gateway (readonly) server
- listening on /ip4/0.0.0.0/tcp/8080
-
-You can now stop watching the log.
-
-Run ipfs commands:
-
- docker exec ipfs_host ipfs
-
-For example: connect to peers
-
- docker exec ipfs_host ipfs swarm peers
-
-Add files:
-
- cp -r $ipfs_staging
- docker exec ipfs_host ipfs add -r /export/
-
-Stop the running container:
-
- docker stop ipfs_host
-
-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:
-
- 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
-
-#### Private swarms inside Docker
-
-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`.
-
- docker run -d --name ipfs_host -e IPFS_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
-
-The swarm key initialization can also be done using docker secrets **(requires docker swarm or docker-compose)**:
-
- cat your_swarm.key | docker secret create swarm_key_secret -
- 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
-
-#### Key rotation inside Docker
-
-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`:
-
-```sh
-# given container named 'ipfs-test' that persists repo at /path/to/persisted/.ipfs
-$ docker run -d --name ipfs-test -v /path/to/persisted/.ipfs:/data/ipfs ipfs/go-ipfs:v0.7.0
-$ docker stop ipfs-test
-
-# key rotation works like this (old key saved under 'old-self')
-$ docker run --rm -it -v /path/to/persisted/.ipfs:/data/ipfs ipfs/go-ipfs:v0.7.0 key rotate -o old-self -t ed25519
-$ docker start ipfs-test # will start with the new key
-```
-
### Troubleshooting
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.
]