Home

Awesome

helia-http-gateway

ipfs.tech Discuss codecov CI

HTTP IPFS Gateway implemented using Helia

About

<!-- !IMPORTANT! Everything in this README between "# About" and "# Install" is automatically generated and will be overwritten the next time the doc generator is run. To make changes to this section, please update the @packageDocumentation section of src/index.js or src/index.ts To experiment with formatting, please run "npm run docs" from the root of this repo and examine the changes made. -->

A Dockerized application that implements the HTTP IPFS-gateway API spec and responds to the incoming requests using Helia to fetch the content from IPFS.

Run from the github container registry

$ docker run -it -p 8080:8080 ghcr.io/ipfs/helia-http-gateway:latest

See https://github.com/ipfs/helia-http-gateway/pkgs/container/helia-http-gateway for more information.

Run Using Docker Compose

$ docker-compose up

Run Using Docker

Build

$ docker build . --tag helia-http-gateway:local

Pass the explicit platform when building on a Mac.

$ docker build . --platform linux/arm64 --tag helia-http-gateway:local-arm64

Running

$ docker run -it -p 8080:8080 -e DEBUG="helia-http-gateway*" helia-http-gateway:local # or helia-http-gateway:local-arm64

Run without Docker

### Build

$ npm run build

Running

$ npm start

Supported Environment Variables

VariableDescriptionDefault
DEBUGDebug level''
FASTIFY_DEBUGDebug level for fastify's logger''
PORTPort to listen on8080
HOSTHost to listen on0.0.0.0
USE_SUBDOMAINSWhether to use origin isolationtrue
METRICSWhether to enable prometheus metrics. Any value other than 'true' will disable metrics.true
USE_BITSWAPUse bitswap to fetch content from IPFStrue
USE_TRUSTLESS_GATEWAYSWhether to fetch content from trustless-gateways or nottrue
TRUSTLESS_GATEWAYSComma separated list of trusted gateways to fetch content fromDefined in Helia
USE_LIBP2PWhether to use libp2p networkingtrue
ECHO_HEADERSA debug flag to indicate whether you want to output request and response headersfalse
USE_DELEGATED_ROUTINGWhether to use the delegated routing v1 APItrue
DELEGATED_ROUTING_V1_HOSTHostname to use for delegated routing v1https://delegated-ipfs.dev
USE_DHT_ROUTINGWhether to use @libp2p/kad-dht for routing when libp2p is enabledtrue
USE_SESSIONSIf true, use a blockstore session per IPFS/IPNS pathtrue
<!-- TODO: currently broken when used in docker, but they work when running locally (you can cache datastore and blockstore locally to speed things up if you want) | `FILE_DATASTORE_PATH` | Path to use with a datastore-level passed to Helia as the datastore | `null`; memory datastore is used by default. | | `FILE_BLOCKSTORE_PATH` | Path to use with a blockstore-fs passed to Helia as the blockstore | `null`; memory blockstore is used by default. | -->

See the source of truth for all process.env.<name> environment variables at src/constants.ts.

You can also see some recommended environment variable configurations at:

Running with custom configurations

Note that any of the following calls to docker can be replaced with something like MY_ENV_VAR="MY_VALUE" npm run start

Disable libp2p

$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e USE_LIBP2P="false" helia

Disable bitswap

$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e USE_BITSWAP="false" helia

Disable trustless gateways

$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e USE_TRUSTLESS_GATEWAYS="false" helia

Customize trustless gateways

$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e TRUSTLESS_GATEWAYS="https://ipfs.io,https://dweb.link" helia
<!-- #### With file datastore and blockstore **NOTE:** Not currently supported due to docker volume? issues. ```sh $ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e FILE_DATASTORE_PATH="./datastore" -e FILE_BLOCKSTORE_PATH="./blockstore" helia # and if you want to re-use a volume from your host: $ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e FILE_DATASTORE_PATH="./datastore" -e FILE_BLOCKSTORE_PATH="./blockstore" -v ./datastore:/datastore -v ./blockstore:/blockstore helia ``` -->

E2E Testing

We have some tests enabled that simulate running inside of ProbeLab's Tiros, via playwright. These tests request the same paths from ipfs.io and ensure that the resulting text matches. This is not a direct replacement for gateway conformance testing, but helps us ensure the helia-http-gateway is working as expected.

By default, these tests:

  1. Run in serial
  2. Allow for up to 5 failures before failing the whole suite run.
  3. Have an individual test timeout of two minutes.

Run e2e tests locally

$ npm run test:e2e # run all tests
$ npm run test:e2e -- ${PLAYWRIGHT_OPTIONS} # run tests with custom playwright options.

Get clinicjs flamecharts and doctor reports from e2e tests

$ npm run test:e2e-doctor # Run the dev server with clinicjs doctor, execute e2e tests, and generate a report.
$ npm run test:e2e-flame # Run the dev server with clinicjs flame, execute e2e tests, and generate a report.

Metrics

Running with METRICS=true will enable collecting Fastify/libp2p metrics and will expose a prometheus collection endpoint at http://localhost:8080/metrics

js-libp2p metrics are collected by default, but can be disabled by setting USE_LIBP2P_METRICS=false. Find out more details at https://github.com/libp2p/js-libp2p/tree/main/packages/metrics-prometheus

Viewing metrics

See Metrics config for more information on how to view the generated metrics.

Install

$ npm i @helia/http-gateway

License

Licensed under either of

Contribute

Contributions welcome! Please check out the issues.

Also see our contributing document for more information on how we work, and about contributing in general.

Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.