{"id":15152873,"url":"https://github.com/ipfs/ipfs-check","last_synced_at":"2025-12-16T02:03:49.359Z","repository":{"id":37781068,"uuid":"393274811","full_name":"ipfs/ipfs-check","owner":"ipfs","description":"A tool for checking the accessibility of your data by IPFS peers","archived":false,"fork":false,"pushed_at":"2025-03-28T13:08:20.000Z","size":513,"stargazers_count":43,"open_issues_count":9,"forks_count":16,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-10T03:57:12.760Z","etag":null,"topics":["ipfs"],"latest_commit_sha":null,"homepage":"https://check.ipfs.network","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-06T06:22:52.000Z","updated_at":"2025-04-04T04:14:51.000Z","dependencies_parsed_at":"2024-06-21T15:26:02.022Z","dependency_job_id":"4d3a19ce-3159-4756-88b5-16627727c87a","html_url":"https://github.com/ipfs/ipfs-check","commit_stats":{"total_commits":140,"total_committers":16,"mean_commits":8.75,"dds":"0.48571428571428577","last_synced_commit":"a727540762dd01322dd066f31c1cb080b3141a82"},"previous_names":["aschmahmann/ipfs-check","ipfs/ipfs-check"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fipfs-check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fipfs-check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fipfs-check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fipfs-check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs","download_url":"https://codeload.github.com/ipfs/ipfs-check/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154997,"owners_count":21056542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ipfs"],"created_at":"2024-09-26T16:40:55.485Z","updated_at":"2025-12-16T02:03:49.353Z","avatar_url":"https://github.com/ipfs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ipfs-check\n\n\u003e Check if you can find your content on IPFS\n\nA debugging tool for checking the retrievability of data by IPFS peers\n\n## Install\n\n`go install github.com/ipfs/ipfs-check@latest` will build and install the server binary in your global Go binary directory (e.g. `~/go/bin`)\n\n### Docker\n\nAutomated Docker container releases are available from the [Github container registry](https://github.com/ipfs/ipfs-check/pkgs/container/ipfs-check):\n\n- Releases\n  - `latest` always points at the latest stable release\n  - `vN.N.N` point at a specific [release tag](https://github.com/ipfs/ipfs-check/releases)\n- Unreleased developer builds\n  - `main-latest` always points at the `HEAD` of the `main` branch\n  - `main-YYYY-DD-MM-GITSHA` points at a specific commit from the `main` branch\n- ⚠️ Experimental, unstable builds\n  - `staging-latest` always points at the `HEAD` of the `staging` branch\n  - `staging-YYYY-DD-MM-GITSHA` points at a specific commit from the `staging` branch\n  - This tag is used by developers for internal testing, not intended for end users\n\nWhen using Docker, make sure to pass necessary config via `-e`:\n```console\n$ docker pull ghcr.io/ipfs/ipfs-check:main-latest\n$ docker run --rm -it --net=host -e IPFS_CHECK_ACCELERATED_DHT=true ghcr.io/ipfs/ipfs-check:main-latest\n```\n\nLearn available variables via `./ipfs-check --help`\n\n## Build\n\n### Backend\n\n`go build` will build the `./ipfs-check` binary in your local directory\n\n### Frontend\n\nThe web assets in `./web` directory are embedded directly into the Go binary and served as-is. No build step is required for deployment - the pre-built CSS and static files are already committed to the repository.\n\nThe latest version from the `main` branch is automatically deployed to https://check.ipfs.network for convenience.\n\nIf you need to modify the web interface styles:\n1. Make changes to `web/input.css`\n2. Run `npm ci` and `npm run build` in the `web` directory (see `web/README.md` for details)\n3. Commit the updated `web/output.css` file\n\n\u003e [!IMPORTANT]\n\u003e Breaking changes to the HTTP API or frontend MUST be avoided. The new `./web` should always work with old backend versions to ensure compatibility.\n\nFor production deployments, you'll want a proxy for HTTPS support on the Go server.\n\n\n## Running locally\n\n### Terminal 1\n\n```console\n$ go build\n$ ./ipfs-check\nStarting ipfs-check\n...\n2024/08/29 20:42:34 Please wait, initializing accelerated-dht client.. (mapping Amino DHT may takes 5 or more minutes)\n2024/08/29 20:42:34 Accelerated DHT client ready\n2024/08/29 20:46:59 Backend ready and listening on [::]:3333\n2024/08/29 20:46:59 Test fronted at http://localhost:3333/web/?backendURL=http://localhost:3333\n2024/08/29 20:46:59 Ready to start serving.\n```\n\nAs a convenience, a test frontend is provided at \u003chttp://localhost:3333/web/?backendURL=http://localhost:3333\u003e.\n\n### Terminal 2\n\nIf you don't want to use test HTTP server from ipfs-check itself, feel free to\nuse any other tool to serve the contents of the /web folder (you can open the\nhtml file directly in your browser).\n\n```\nnpx -y serve -l 3000 web\n# Then open http://localhost:3000?backendURL=http://localhost:3333\n```\n\n## Logging\n\nLogging verbosity can be controlled via environment variables from [go-log](https://github.com/ipfs/go-log/?tab=readme-ov-file#environment-variables).\n\nFor example, to enable debug logs for specific subsystems:\n\n```console\n$ GOLOG_LOG_LEVEL=info,dht=debug,net/identify=debug ./ipfs-check\n```\n\n## Running a check\n\nTo run a check, make an http call with the `cid` and `multiaddr` query parameters:\n\n```bash\n$ curl \"localhost:3333/check?cid=bafybeicklkqcnlvtiscr2hzkubjwnwjinvskffn4xorqeduft3wq7vm5u4\u0026multiaddr=/p2p/12D3KooWRBy97UB99e3J6hiPesre1MZeuNQvfan4gBziswrRJsNK\"\n```\n\nNote that the `multiaddr` can be:\n\n- A `multiaddr` with just a Peer ID, i.e. `/p2p/PeerID`. In this case, the server will attempt to resolve this Peer ID with the DHT and connect to any of resolved addresses.\n- A `multiaddr` with an address port and transport, and Peer ID, e.g. `/ip4/140.238.164.150/udp/4001/quic-v1/p2p/12D3KooWRTUNZVyVf7KBBNZ6MRR5SYGGjKzS6xyiU5zBeY9wxomo/p2p-circuit/p2p/12D3KooWRBy97UB99e3J6hiPesre1MZeuNQvfan4gBziswrRJsNK`. In this case, the Bitswap check will only happen using the passed multiaddr.\n\n### Check results\n\nThe server performs several checks depending on whether you also pass a **multiaddr** or just a **cid**.\n\n#### Results when only a `cid` is passed\n\nThe results of the check are expressed by the `cidCheckOutput` type:\n\n```go\ntype cidCheckOutput *[]providerOutput\n\ntype providerOutput struct {\n\tID                       string\n\tConnectionError          string\n\tAddrs                    []string\n\tConnectionMaddrs         []string\n\tDataAvailableOverBitswap BitswapCheckOutput\n\tDataAvailableOverHTTP    HTTPCheckOutput\n\tSource                   string\n}\n```\n\nThe `providerOutput` type contains the following fields:\n\n- `ID`: The peer ID of the provider.\n- `ConnectionError`: An error message if the connection to the provider failed.\n- `Addrs`: The multiaddrs of the provider from the DHT.\n- `ConnectionMaddrs`: The multiaddrs that were used to connect to the provider.\n- `DataAvailableOverBitswap`: The result of the Bitswap check.\n- `DataAvailableOverHTTP`: The result of the HTTP check.\n- `Source`: The source of the provider (either \"IPNI\" or \"Amino DHT\").\n\n#### Results when a `multiaddr` and a `cid` are passed\n\nThe results of the check are expressed by the `peerCheckOutput` type:\n\n```go\ntype peerCheckOutput struct {\n\tConnectionError              string\n\tPeerFoundInDHT              map[string]int\n\tProviderRecordFromPeerInDHT  bool\n\tProviderRecordFromPeerInIPNI bool\n\tConnectionMaddrs             []string\n\tDataAvailableOverBitswap     BitswapCheckOutput\n\tDataAvailableOverHTTP        HTTPCheckOutput\n}\n\ntype BitswapCheckOutput struct {\n\tEnabled   bool\n\tDuration  time.Duration\n\tFound     bool\n\tResponded bool\n\tError     string\n}\n\ntype HTTPCheckOutput struct {\n\tEnabled   bool\n\tDuration  time.Duration\n\tEndpoints []multiaddr.Multiaddr\n\tConnected bool\n\tRequested bool\n\tFound     bool\n\tError     string\n}\n```\n\nThe check performs several validations:\n\n1. Is the CID advertised in the DHT by the Passed PeerID (or later IPNI)?\n   - `ProviderRecordFromPeerInDHT`: Whether the peer has a provider record in the DHT\n   - `ProviderRecordFromPeerInIPNI`: Whether the peer has a provider record in IPNI\n\n2. Are the peer's addresses discoverable?\n   - `PeerFoundInDHT`: Map of discovered addresses and their frequency in the DHT\n\n3. Is the peer contactable with the address the user gave us?\n   - `ConnectionError`: Empty if connection successful, otherwise contains the error\n   - `ConnectionMaddrs`: The multiaddrs used to connect (includes both relay and direct addresses if NAT traversal occurred)\n\n4. Is the data available over Bitswap?\n   - `DataAvailableOverBitswap`: Contains:\n     - `Enabled`: Whether Bitswap check was performed\n     - `Duration`: How long the check took\n     - `Found`: Whether the block was found\n     - `Responded`: Whether the peer responded\n     - `Error`: Any error that occurred\n\n5. Is the data available over HTTP?\n   - `DataAvailableOverHTTP`: Contains:\n     - `Enabled`: Whether HTTP check was performed\n     - `Duration`: How long the check took\n     - `Endpoints`: List of HTTP multiaddrs\n     - `Connected`: Whether connection was successful\n     - `Requested`: Whether the request was sent\n     - `Found`: Whether the block was found\n     - `Error`: Any error that occurred\n\n## Metrics\n\nThe ipfs-check server is instrumented and exposes two Prometheus metrics endpoints:\n\n- `/metrics` exposes [go-libp2p metrics](https://blog.libp2p.io/2023-08-15-metrics-in-go-libp2p/) and http metrics for the check endpoint.\n\n### Securing the metrics endpoints\n\nTo add HTTP basic auth to the two metrics endpoints, you can use the `--metrics-auth-username` and `--metrics-auth-password` flags:\n\n```\n./ipfs-check --metrics-auth-username=user --metrics-auth-password=pass\n```\n\nAlternatively, you can use the `IPFS_CHECK_METRICS_AUTH_USER` and `IPFS_CHECK_METRICS_AUTH_PASS` env vars.\n\n## License\n\n[SPDX-License-Identifier: Apache-2.0 OR MIT](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fipfs-check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs%2Fipfs-check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fipfs-check/lists"}