{"id":14956159,"url":"https://github.com/ipfs/helia-http-gateway","last_synced_at":"2025-11-17T03:29:26.078Z","repository":{"id":199302421,"uuid":"696944341","full_name":"ipfs/helia-http-gateway","owner":"ipfs","description":"Run Helia NodeJS in a Docker Container.","archived":false,"fork":false,"pushed_at":"2025-05-22T10:56:15.000Z","size":7012,"stargazers_count":16,"open_issues_count":41,"forks_count":11,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-23T04:26:22.615Z","etag":null,"topics":["docker","helia-nodejs","ipfs-helia"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","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","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}},"created_at":"2023-09-26T18:24:47.000Z","updated_at":"2025-05-21T11:32:53.000Z","dependencies_parsed_at":"2024-01-24T01:38:52.279Z","dependency_job_id":"3f8866d5-fc1e-4676-ae05-d4be7015d016","html_url":"https://github.com/ipfs/helia-http-gateway","commit_stats":null,"previous_names":["ipfs/helia-docker","ipfs/helia-http-gateway"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ipfs/helia-http-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fhelia-http-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fhelia-http-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fhelia-http-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fhelia-http-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs","download_url":"https://codeload.github.com/ipfs/helia-http-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fhelia-http-gateway/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265013445,"owners_count":23698041,"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":["docker","helia-nodejs","ipfs-helia"],"created_at":"2024-09-24T13:12:24.301Z","updated_at":"2025-10-23T19:58:08.133Z","avatar_url":"https://github.com/ipfs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# helia-http-gateway\n\n# @helia/http-gateway\n\n[![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)\n[![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)\n[![codecov](https://img.shields.io/codecov/c/github/ipfs/helia-http-gateway.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia-http-gateway)\n[![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia-http-gateway/js-test-and-release.yml?branch=main\\\u0026style=flat-square)](https://github.com/ipfs/helia-http-gateway/actions/workflows/js-test-and-release.yml?query=branch%3Amain)\n\n\u003e HTTP IPFS Gateway implemented using Helia\n\n# About\n\n\u003c!--\n\n!IMPORTANT!\n\nEverything in this README between \"# About\" and \"# Install\" is automatically\ngenerated and will be overwritten the next time the doc generator is run.\n\nTo make changes to this section, please update the @packageDocumentation section\nof src/index.js or src/index.ts\n\nTo experiment with formatting, please run \"npm run docs\" from the root of this\nrepo and examine the changes made.\n\n--\u003e\n\nA 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.\n\n## Run from the github container registry\n\n```sh\n$ docker run -it -p 8080:8080 ghcr.io/ipfs/helia-http-gateway:latest\n```\n\nSee \u003chttps://github.com/ipfs/helia-http-gateway/pkgs/container/helia-http-gateway\u003e for more information.\n\n## Run Using Docker Compose\n\n```sh\n$ docker-compose up\n```\n\n## Run Using Docker\n\n### Build\n\n```sh\n$ docker build . --tag helia-http-gateway:local\n```\n\nPass the explicit platform when building on a Mac.\n\n```sh\n$ docker build . --platform linux/arm64 --tag helia-http-gateway:local-arm64\n```\n\n### Running\n\n```sh\n$ docker run -it -p 8080:8080 -e DEBUG=\"helia-http-gateway*\" helia-http-gateway:local # or helia-http-gateway:local-arm64\n```\n\n## Run without Docker\n\n\\### Build\n\n```sh\n$ npm run build\n```\n\n### Running\n\n```sh\n$ npm start\n```\n\n## Supported Environment Variables\n\n| Variable                    | Description                                                                                                                                    | Default                                                                                                                 |\n| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `DEBUG`                     | Debug level                                                                                                                                    | `''`                                                                                                                    |\n| `FASTIFY_DEBUG`             | Debug level for fastify's logger                                                                                                               | `''`                                                                                                                    |\n| `PORT`                      | Port to listen on                                                                                                                              | `8080`                                                                                                                  |\n| `HOST`                      | Host to listen on                                                                                                                              | `0.0.0.0`                                                                                                               |\n| `USE_SUBDOMAINS`            | Whether to use [origin isolation](https://docs.ipfs.tech/how-to/gateway-best-practices/#use-subdomain-gateway-resolution-for-origin-isolation) | `true`                                                                                                                  |\n| `METRICS`                   | Whether to enable prometheus metrics. Any value other than 'true' will disable metrics.                                                        | `true`                                                                                                                  |\n| `USE_BITSWAP`               | Use bitswap to fetch content from IPFS                                                                                                         | `true`                                                                                                                  |\n| `USE_TRUSTLESS_GATEWAYS`    | Whether to fetch content from trustless-gateways or not                                                                                        | `true`                                                                                                                  |\n| `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) |\n| `USE_LIBP2P`                | Whether to use libp2p networking                                                                                                               | `true`                                                                                                                  |\n| `ECHO_HEADERS`              | A debug flag to indicate whether you want to output request and response headers                                                               | `false`                                                                                                                 |\n| `USE_DELEGATED_ROUTING`     | Whether to use the delegated routing v1 API                                                                                                    | `true`                                                                                                                  |\n| `DELEGATED_ROUTING_V1_HOST` | Hostname to use for delegated routing v1                                                                                                       | `https://delegated-ipfs.dev`                                                                                            |\n| `USE_DHT_ROUTING`           | Whether to use @libp2p/kad-dht for routing when libp2p is enabled                                                                              | `true`                                                                                                                  |\n| `USE_SESSIONS`              | If true, use a blockstore session per IPFS/IPNS path                                                                                           | `true`                                                                                                                  |\n\n\u003c!--\nTODO: 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)\n| `FILE_DATASTORE_PATH` | Path to use with a datastore-level passed to Helia as the datastore | `null`; memory datastore is used by default. |\n| `FILE_BLOCKSTORE_PATH` | Path to use with a blockstore-fs passed to Helia as the blockstore | `null`; memory blockstore is used by default. |\n--\u003e\n\nSee the source of truth for all `process.env.\u003cname\u003e` environment variables at [src/constants.ts](src/constants.ts).\n\nYou can also see some recommended environment variable configurations at:\n\n- [./.env-all](./.env-all)\n- [./.env-delegated-routing](./.env-delegated-routing)\n- [./.env-gwc](./.env-gwc)\n- [./.env-trustless-only](./.env-trustless-only)\n\n### Running with custom configurations\n\nNote that any of the following calls to docker can be replaced with something like `MY_ENV_VAR=\"MY_VALUE\" npm run start`\n\n#### Disable libp2p\n\n```sh\n$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG=\"helia-http-gateway*\" -e USE_LIBP2P=\"false\" helia\n```\n\n#### Disable bitswap\n\n```sh\n$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG=\"helia-http-gateway*\" -e USE_BITSWAP=\"false\" helia\n```\n\n#### Disable trustless gateways\n\n```sh\n$ docker run -it -p $RPC_PORT:5001 -p $HTTP_PORT:8080 -e DEBUG=\"helia-http-gateway*\" -e USE_TRUSTLESS_GATEWAYS=\"false\" helia\n```\n\n#### Customize trustless gateways\n\n```sh\n$ 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\n```\n\n\u003c!--\n#### With file datastore and blockstore\n\n**NOTE:** Not currently supported due to docker volume? issues.\n\n```sh\n$ 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\n# and if you want to re-use a volume from your host:\n$ 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\n```\n--\u003e\n\n## E2E Testing\n\nWe 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.\n\nBy default, these tests:\n\n1. Run in serial\n2. Allow for up to 5 failures before failing the whole suite run.\n3. Have an individual test timeout of two minutes.\n\n### Run e2e tests locally\n\n```sh\n$ npm run test:e2e # run all tests\n$ npm run test:e2e -- ${PLAYWRIGHT_OPTIONS} # run tests with custom playwright options.\n\n```\n\n### Get clinicjs flamecharts and doctor reports from e2e tests\n\n```sh\n$ npm run test:e2e-doctor # Run the dev server with clinicjs doctor, execute e2e tests, and generate a report.\n$ npm run test:e2e-flame # Run the dev server with clinicjs flame, execute e2e tests, and generate a report.\n```\n\n## Metrics\n\nRunning with `METRICS=true` will enable collecting Fastify/libp2p metrics and\nwill expose a prometheus collection endpoint at \u003chttp://localhost:8080/metrics\u003e\n\njs-libp2p metrics are collected by default, but can be disabled by setting `USE_LIBP2P_METRICS=false`. Find out more details at \u003chttps://github.com/libp2p/js-libp2p/tree/main/packages/metrics-prometheus\u003e\n\n### Viewing metrics\n\nSee [Metrics config](./config/README.md#metrics) for more information on how to view the generated metrics.\n\n# Install\n\n```console\n$ npm i @helia/http-gateway\n```\n\n# API Docs\n\n- \u003chttps://ipfs.github.io/helia-http-gateway\u003e\n\n# License\n\nLicensed under either of\n\n- Apache 2.0, ([LICENSE-APACHE](https://github.com/ipfs/helia-http-gateway/LICENSE-APACHE) / \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n- MIT ([LICENSE-MIT](https://github.com/ipfs/helia-http-gateway/LICENSE-MIT) / \u003chttp://opensource.org/licenses/MIT\u003e)\n\n# Contribute\n\nContributions welcome! Please check out [the issues](https://github.com/ipfs/helia-http-gateway/issues).\n\nAlso 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.\n\nPlease 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).\n\nUnless 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.\n\n[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fhelia-http-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs%2Fhelia-http-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fhelia-http-gateway/lists"}