HTTP IPFS Gateway implemented using Helia
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.
$ 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.
$ docker-compose up
$ 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
$ docker run -it -p 8080:8080 -e DEBUG="helia-http-gateway*" helia-http-gateway:local # or helia-http-gateway:local-arm64
### Build
$ npm run build
$ npm start
Variable | Description | Default |
---|---|---|
DEBUG |
Debug level | '' |
FASTIFY_DEBUG |
Debug level for fastify's logger | '' |
PORT |
Port to listen on | 8080 |
HOST |
Host to listen on | 0.0.0.0 |
USE_SUBDOMAINS |
Whether to use origin isolation | true |
METRICS |
Whether to enable prometheus metrics. Any value other than 'true' will disable metrics. | true |
USE_BITSWAP |
Use bitswap to fetch content from IPFS | true |
USE_TRUSTLESS_GATEWAYS |
Whether to fetch content from trustless-gateways or not | true |
TRUSTLESS_GATEWAYS |
Comma separated list of trusted gateways to fetch content from | Defined in Helia |
USE_LIBP2P |
Whether to use libp2p networking | true |
ECHO_HEADERS |
A debug flag to indicate whether you want to output request and response headers | false |
USE_DELEGATED_ROUTING |
Whether to use the delegated routing v1 API | true |
DELEGATED_ROUTING_V1_HOST |
Hostname to use for delegated routing v1 | https://delegated-ipfs.dev |
USE_DHT_ROUTING |
Whether to use @libp2p/kad-dht for routing when libp2p is enabled | true |
USE_SESSIONS |
If true, use a blockstore session per IPFS/IPNS path | true |
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:
Note that any of the following calls to docker can be replaced with something like MY_ENV_VAR="MY_VALUE" npm run start
$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e USE_LIBP2P="false" helia
$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e USE_BITSWAP="false" helia
$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e USE_TRUSTLESS_GATEWAYS="false" helia
$ 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
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:
- Run in serial
- Allow for up to 5 failures before failing the whole suite run.
- Have an individual test timeout of two minutes.
$ npm run test:e2e # run all tests
$ npm run test:e2e -- ${PLAYWRIGHT_OPTIONS} # run tests with custom playwright options.
$ 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.
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
See Metrics config for more information on how to view the generated metrics.
$ npm i helia-http-gateway
Licensed under either of
- Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
- MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)
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.
http://bafkreid7qoywk77r7rj3slobqfekdvs57qwuwh5d2z3sqsw52iabe3mqne.ipfs.localhost:4867/ http://bafkreid7qoywk77r7rj3slobqfekdvs57qwuwh5d2z3sqsw52iabe3mqne.ipfs.localhost:8080/