https://github.com/ipfs/helia-http-gateway
Run Helia NodeJS in a Docker Container.
https://github.com/ipfs/helia-http-gateway
docker helia-nodejs ipfs-helia
Last synced: 8 months ago
JSON representation
Run Helia NodeJS in a Docker Container.
- Host: GitHub
- URL: https://github.com/ipfs/helia-http-gateway
- Owner: ipfs
- License: apache-2.0
- Created: 2023-09-26T18:24:47.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-05-22T10:56:15.000Z (about 1 year ago)
- Last Synced: 2025-05-23T04:26:22.615Z (about 1 year ago)
- Topics: docker, helia-nodejs, ipfs-helia
- Language: TypeScript
- Homepage:
- Size: 6.69 MB
- Stars: 16
- Watchers: 7
- Forks: 11
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# helia-http-gateway
# @helia/http-gateway
[](https://ipfs.tech)
[](https://discuss.ipfs.tech)
[](https://codecov.io/gh/ipfs/helia-http-gateway)
[](https://github.com/ipfs/helia-http-gateway/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
> HTTP IPFS Gateway implemented using Helia
# About
A Dockerized application that implements the [HTTP IPFS-gateway API](https://docs.ipfs.tech/concepts/ipfs-gateway/#gateway-types) spec and responds to the incoming requests using [Helia](https://github.com/ipfs/helia) to fetch the content from IPFS.
## Run from the github container registry
```sh
$ docker run -it -p 8080:8080 ghcr.io/ipfs/helia-http-gateway:latest
```
See for more information.
## Run Using Docker Compose
```sh
$ docker-compose up
```
## Run Using Docker
### Build
```sh
$ docker build . --tag helia-http-gateway:local
```
Pass the explicit platform when building on a Mac.
```sh
$ docker build . --platform linux/arm64 --tag helia-http-gateway:local-arm64
```
### Running
```sh
$ 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
```sh
$ npm run build
```
### Running
```sh
$ npm start
```
## Supported Environment Variables
| 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](https://docs.ipfs.tech/how-to/gateway-best-practices/#use-subdomain-gateway-resolution-for-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](https://github.com/ipfs/helia/blob/main/packages/helia/src/block-brokers/trustless-gateway/index.ts) |
| `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.` environment variables at [src/constants.ts](src/constants.ts).
You can also see some recommended environment variable configurations at:
- [./.env-all](./.env-all)
- [./.env-delegated-routing](./.env-delegated-routing)
- [./.env-gwc](./.env-gwc)
- [./.env-trustless-only](./.env-trustless-only)
### 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
```sh
$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e USE_LIBP2P="false" helia
```
#### Disable bitswap
```sh
$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG="helia-http-gateway*" -e USE_BITSWAP="false" helia
```
#### Disable trustless gateways
```sh
$ 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
```sh
$ 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
```
## E2E Testing
We have some tests enabled that simulate running inside of [ProbeLab's Tiros](https://github.com/plprobelab/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](https://github.com/ipfs/gateway-conformance), 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
```sh
$ 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
```sh
$ 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
js-libp2p metrics are collected by default, but can be disabled by setting `USE_LIBP2P_METRICS=false`. Find out more details at
### Viewing metrics
See [Metrics config](./config/README.md#metrics) for more information on how to view the generated metrics.
# Install
```console
$ npm i @helia/http-gateway
```
# API Docs
-
# License
Licensed under either of
- Apache 2.0, ([LICENSE-APACHE](https://github.com/ipfs/helia-http-gateway/LICENSE-APACHE) / )
- MIT ([LICENSE-MIT](https://github.com/ipfs/helia-http-gateway/LICENSE-MIT) / )
# Contribute
Contributions welcome! Please check out [the issues](https://github.com/ipfs/helia-http-gateway/issues).
Also see our [contributing document](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) 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](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
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.
[](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)