From 96f3007b55169d5b178b4e0563ec2dda6e29d3f5 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Fri, 14 Mar 2025 17:55:35 +0100
Subject: [PATCH] docs(readme): update min. requirements + cleanup (#10750)
* docs(readme): update min. requirements + cleanup
Adding note about extra memory requirement due to
https://github.com/ipfs/kubo/commit/ba22102a640b3f41804319981d83908c96a96275
* docs(config): memory cost of buffered provider
Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com>
---
README.md | 32 +++++++++++++++-----------------
docs/config.md | 7 ++++++-
2 files changed, 21 insertions(+), 18 deletions(-)
diff --git a/README.md b/README.md
index 4970cd9af..2e6766877 100644
--- a/README.md
+++ b/README.md
@@ -12,19 +12,19 @@
<a href="https://ipfs.tech"><img src="https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square" alt="Official Part of IPFS Project"></a>
<a href="https://discuss.ipfs.tech"><img alt="Discourse Forum" src="https://img.shields.io/discourse/posts?server=https%3A%2F%2Fdiscuss.ipfs.tech"></a>
<a href="https://matrix.to/#/#ipfs-space:ipfs.io"><img alt="Matrix" src="https://img.shields.io/matrix/ipfs-space%3Aipfs.io?server_fqdn=matrix.org"></a>
- <a href="https://github.com/ipfs/kubo/actions"><img src="https://img.shields.io/github/actions/workflow/status/ipfs/kubo/build.yml?branch=master" alt="ci"></a>
+ <a href="https://github.com/ipfs/kubo/actions"><img src="https://img.shields.io/github/actions/workflow/status/ipfs/kubo/gobuild.yml?branch=master"></a>
<a href="https://github.com/ipfs/kubo/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/ipfs/kubo?filter=!*rc*"></a>
- <a href="https://godoc.org/github.com/ipfs/kubo"><img src="https://img.shields.io/badge/godoc-reference-5272B4.svg?style=flat-square" alt="godoc reference"></a>
</p>
<hr />
## What is Kubo?
-Kubo was the first IPFS implementation and is the most widely used one today. Implementing the *Interplanetary Filesystem* - the Web3 standard for content-addressing, interoperable with HTTP. Thus powered by IPLD's data models and the libp2p for network communication. Kubo is written in Go.
+Kubo was the first IPFS implementation and is the most widely used one today. Implementing the *Interplanetary Filesystem* - the standard for content-addressing on the Web, interoperable with HTTP. Thus powered by future-proof data models and the libp2p for network communication. Kubo is written in Go.
Featureset
- Runs an IPFS-Node as a network service that is part of LAN and WAN DHT
+- Native support for UnixFS (most popular way to represent files and directories on IPFS)
- [HTTP Gateway](https://specs.ipfs.tech/http-gateways/) (`/ipfs` and `/ipns`) functionality for trusted and [trustless](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) content retrieval
- [HTTP Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) (`/routing/v1`) client and server implementation for [delegated routing](./docs/delegated-routing.md) lookups
- [HTTP Kubo RPC API](https://docs.ipfs.tech/reference/kubo/rpc/) (`/api/v0`) to access and control the daemon
@@ -64,12 +64,11 @@ Before opening an issue, consider using one of the following locations to ensure
- [Next milestones](#next-milestones)
- [Table of Contents](#table-of-contents)
- [Security Issues](#security-issues)
-- [Minimal System Requirements](#minimal-system-requirements)
- [Install](#install)
+ - [Minimal System Requirements](#minimal-system-requirements)
- [Docker](#docker)
- [Official prebuilt binaries](#official-prebuilt-binaries)
- [Updating](#updating)
- - [Using ipfs-update](#using-ipfs-update)
- [Downloading builds using IPFS](#downloading-builds-using-ipfs)
- [Unofficial Linux packages](#unofficial-linux-packages)
- [ArchLinux](#arch-linux)
@@ -112,16 +111,21 @@ Before opening an issue, consider using one of the following locations to ensure
Please follow [`SECURITY.md`](SECURITY.md).
-### Minimal System Requirements
+## Install
-IPFS can run on most Linux, macOS, and Windows systems. We recommend running it on a machine with at least 6 GB of RAM and 2 CPU cores (ideally more, Kubo is highly parallel).
+The canonical download instructions for IPFS are over at: https://docs.ipfs.tech/install/. It is **highly recommended** you follow those instructions if you are not interested in working on IPFS development.
-> [!CAUTION]
-> On systems with less memory, it may not be completely stable, and you run on your own risk.
+For production use, Release Docker images (below) are recommended.
-## Install
+### Minimal System Requirements
-The canonical download instructions for IPFS are over at: https://docs.ipfs.tech/install/. It is **highly recommended** you follow those instructions if you are not interested in working on IPFS development.
+Kubo runs on most Linux, macOS, and Windows systems. For optimal performance, we recommend at least 6 GB of RAM and 2 CPU cores (more is ideal, as Kubo is highly parallel).
+
+> [!IMPORTANT]
+> Larger pinsets require additional memory, with an estimated ~1 GiB of RAM per 20 million items for reproviding to the Amino DHT.
+
+> [!CAUTION]
+> Systems with less than the recommended memory may experience instability, frequent OOM errors or restarts, and missing data announcement (reprovider window), which can make data fully or partially inaccessible to other peers. Running Kubo on underprovisioned hardware is at your own risk.
### Docker
@@ -170,12 +174,6 @@ If you are unable to access [dist.ipfs.tech](https://dist.ipfs.tech#kubo), you c
#### Updating
-##### Using ipfs-update
-
-IPFS has an updating tool that can be accessed through `ipfs update`. The tool is
-not installed alongside IPFS in order to keep that logic independent of the main
-codebase. To install `ipfs-update` tool, [download it here](https://dist.ipfs.tech/#ipfs-update).
-
##### Downloading builds using IPFS
List the available versions of Kubo (go-ipfs) implementation:
diff --git a/docs/config.md b/docs/config.md
index 5b7aa6140..206d1f719 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -1597,7 +1597,12 @@ Tells reprovider what should be announced. Valid strategies are:
providers for the missing block in the middle of a file, unless the peer
happens to already be connected to a provider and ask for child CID over
bitswap.
-- `"flat"` - same as `all`, announce all CIDs of stored blocks, but without prioritizing anything
+- `"flat"` - same as `all`, announce all CIDs of stored blocks, but without prioritizing anything.
+
+> [!IMPORTANT]
+> Reproviding larger pinsets using the `all`, `pinned`, or `roots` strategies requires additional memory, with an estimated ~1 GiB of RAM per 20 million items for reproviding to the Amino DHT.
+> This is due to the use of a buffered provider, which avoids holding a lock on the entire pinset during the reprovide cycle.
+> The `flat` strategy can be used to lower memory requirements, but only recommended if memory utilization is too high, prioritization of pins is not necessary, and it is acceptable to announce every block cached in the local repository.
Default: `"all"`
--
GitLab