Overhaul IPFS Troubleshooting guides with new content and structure (#2046)

- Overhaul the troubleshooting docs
- Added “Helia Identify” browser‐based identify tool to diagnostic tools page
- Reworked the gateway troubleshooting guide into a general purpose troubleshooting guide which covers gateways too and includes IPFS Check
- Move Kubo troubleshooting instructions into a dedicated page
- Add redirect from the old gateway troubleshooting to the new general troubleshooting guide
- New sidebar category for troubleshooting guides
- Add “IPFS Check” tool description to public utils
- Add mention of reproviding to the providing section in the lifecycle of data page.
- Link to troubleshooting guide from the landing page
---------

Co-authored-by: Daniel N <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Marcin Rataj <[email protected]>

Author: 3 people

.github/styles/pln-ignore.txt

@@ -1,4 +1,3 @@
-atcute
 aave
 accessor
 acls
@@ -11,18 +10,20 @@ arbol
 arbol's
 arbol('s)
 arg
+astro
+atcute
 auditable
 audius
-astro
 auspinner
-bit[ss]wap
 bitswap
+bit[ss]wap
 blockchain
 blockchains
 blockstore
 bool
 bool(ean)
 boolean
+Bootstrappers
 boxo
 browserify
 caddy
@@ -45,6 +46,7 @@ composable
 config
 counterparty
 coworking
+cpu
 cpus
 crowdsourcing
 crypto(currencies)
@@ -53,6 +55,7 @@ dapps
 data('s)
 datastore
 deduplicate
+Denylist
 dep
 deps
 deserialization
@@ -63,6 +66,7 @@ dht
 dhts
 dialable
 dialback
+discoverability
 dns('s)
 dnsaddr
 dnscontrol
@@ -82,14 +86,16 @@ filecoin
 filecorgi
 filesizes
 filestore
-flatf[ss]
 flatfs
+flatf[ss]
 fleek
 fqdns
 gasless
 geospatial
+gif
 git(hub)
 gnutella
+goroutine
 goroutines
 graphsync
 guis
@@ -131,21 +137,21 @@ lastalive
 lastbootstrap
 lastpeer
 leveldb
-libp2p
 libipld
+libp2p
 linux
 lookups
 loopback
 mainnet
 markdown(lint)
 markdownlint
 merkle
+merkleization
 merkleize
-merklizing
-merkleizing
-merkleizes
 merkleized
-merkleization
+merkleizes
+merkleizing
+merklizing
 metadata('s)
 metamask
 minimalistic
@@ -154,12 +160,13 @@ mojitos
 multiaddr
 multiaddr(ess)
 multiaddress
+multiaddresses
 multiaddrs
 multibase
 multicast
 multicodec
-multicodecs
 multicodec(s)
+multicodecs
 multiformats
 multihash
 multihashes
@@ -200,23 +207,26 @@ protobuf
 protocol labs
 protoschool
 proxied
-pub[ss]ub
 pubsub
+pub[ss]ub
 qm
 rabin
 rasterio
+reachability
 readmes
 referenceable
 repo
 repos
+reprovide
 reprovider
 reproviding
 requesters
 retrievability
 roadmaps
+routable
+rsa
 runtime
 runtime's
-rsa
 sandboxed
 satoshi
 satoshi nakamoto
@@ -225,16 +235,18 @@ sharding
 snapshotted
 sneakernet
 sneakernets
+Someguy
+someguy
 stackparse
 stdout
-storj
 storacha
-Someguy
+storj
 subcommand
 substring
 sys
 systemd
 sztandera
+takedown
 testground
 testnet
 toolkits
@@ -272,4 +284,5 @@ whyrusleeping
 wifi
 ws
 wss
+Yamux
 youtube

docs/.vuepress/config.js

@@ -208,11 +208,22 @@ module.exports = {
                 '/how-to/nat-configuration',
                 '/how-to/kubo-rpc-tls-auth',
                 '/how-to/kubo-garbage-collection',
-                '/how-to/troubleshooting',   
+                '/how-to/troubleshooting-kubo',   
                 '/how-to/webtransport',   
                 '/install/run-ipfs-inside-docker',
               ]
             },
+            {
+              title: 'Troubleshooting',
+              sidebarDepth: 1,
+              collapsable: true,
+              children: [
+                '/how-to/troubleshooting',
+                '/how-to/troubleshooting-kubo',
+                '/reference/diagnostic-tools',
+                '/how-to/nat-configuration',
+              ]
+            },
             {
               title: 'Manage files',
               sidebarDepth: 1,
@@ -273,7 +284,7 @@ module.exports = {
               collapsable: true,
               children: [
                 '/how-to/gateway-best-practices',
-                '/how-to/gateway-troubleshooting',
+                '/how-to/troubleshooting',
               ]
             },
             {

docs/.vuepress/redirects

@@ -45,6 +45,7 @@
 /how-to/run-ipfs-inside-docker /install/run-ipfs-inside-docker
 /how-to/ipfs-updater /install/command-line
 /how-to/websites-on-ipfs/link-a-domain /how-to/websites-on-ipfs/custom-domains
+/how-to/gateway-troubleshooting /how-to/troubleshooting
 /install/command-line-quick-start/ /how-to/command-line-quick-start
 /install/js-ipfs/ https://github.com/ipfs/helia/wiki
 /introduction/ /concepts

docs/README.md

@@ -37,6 +37,10 @@ IPFS is a great fit for deploying static sites and dapps, check out the followin
 - [Set up a DNSLink gateway to serve your site via a custom domain](./how-to/websites-on-ipfs/dnslink-gateway.md).
 - [Configure static site generators for publishing to IPFS](./how-to/websites-on-ipfs/static-site-generators.md).
 
+## Troubleshooting
+
+If you're having trouble retrieving or providing data to the IPFS network, check out the [troubleshooting guide](./how-to/troubleshooting.md).
+
 ### Build
 
 You can build apps that leverage IPFS implementations, or use HTTP instead:

docs/concepts/lifecycle.md

@@ -22,7 +22,7 @@ For example, merkleizing a static web application into a UnixFS DAG looks like t
 
 ## 2. Providing
 
-Once the input data has been merkleized and addressed by a CID, the node announces itself as a provider of the CID(s) to the IPFS network, thereby creating a public mapping between the CID and the node. This is typically known as **providing**, other names for this step are **publishing** and **advertising**.
+Once the input data has been merkleized and addressed by a CID, the node announces itself as a provider of the CID(s) to the IPFS network, thereby creating a public mapping between the CID and the node. This is typically known as **providing**, other names for this step are **publishing** **advertising**. On routing systems with built-in expiration/TTL like the Amino DHT, this is also known as **reproviding** to emphasize the continuous nature of the process in which a node advertises provider records.
 
 IPFS nodes announce CID(s) to either the [DHT](./dht.md) or the [IPNI](./ipni.md) — the two content routing systems supported by [IPFS Mainnet](./glossary.md#mainnet).
 

docs/concepts/public-utilities.md

@@ -97,6 +97,18 @@ To increase resilience and implementation diversity, as of 2024, the IPFS Founda
 
 `/dnsaddr/va1.bootstrap.libp2p.io/p2p/12D3KooWKnDdG3iXw9eTFijk3EWSunZcFi54Zka4wmtqtt6rPxc8`.
 
+
+## IPFS Check
+
+[IPFS Check](https://check.ipfs.network) is a diagnostic tool for debugging retrieval by CID. It works by probing retrieval from either a single provider or a set of providers with Bitswap and HTTP (depending on the provider's support). It supports two modes:
+
+- **Single Provider Mode**: Probes retrieval from a single provider with a given CID and multiaddress.
+- **Multi Provider Mode**: Probes retrieval from a set of providers with a given CID. This mode works by routing CIDs the DHT and IPNI, and then probing retrieval from the providers.
+
+The IPFS Foundation provides a hosted version of IPFS Check as a public good, and is available at [check.ipfs.network](https://check.ipfs.network).
+
+The backend is open source at [`ipfs/ipfs-check`](https://github.com/ipfs/ipfs-check), and can be run self-hosted, ideally on a remote server with a public IPv4/IPv6 address in order to get an external perspective.
+
 ## Frequently Asked Questions (FAQs)
 
 ### How is the ipfs.io gateway different from other gateways?