IPFS Web UI

A web interface to IPFS.

Check on your node stats, explore the IPLD powered merkle forest, see peers around the world and manage your files, without needing to touch the CLI.

Files	Explore	Peers	Settings

The IPFS WebUI is a work-in-progress. Help us make it better! We use the issues on this repo to track the work and it's part of the wider IPFS GUI project.

The app uses ipfs-http-client to communicate with your local IPFS node.

The app is built with create-react-app. Please read the docs.

Install

With node >= 8.12 and npm >= 6.4.1 installed, run

> npm install

Usage

When working on the code, run an ipfs daemon, the local dev server, the unit tests, and the storybook component viewer and see the results of your changes as you save files.

In separate shells run the following:

# Run IPFS
> ipfs daemon

# Run the dev server @ http://localhost:3000
> npm start

# Run the unit tests
> npm test

# Run the UI component viewer @ http://localhost:9009
> npm run storybook

Configure IPFS API CORS headers

You must configure your IPFS API at http://127.0.0.1:5001 to allow cross-origin (CORS) requests from your dev server at http://localhost:3000

Similarly if you want to try out pre-release versions at https://webui.ipfs.io you need to add that as an allowed domain too.

Easy mode

Run the cors-config.sh script with:

> ./cors-config.sh

The manual way

> ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["http://localhost:3000", "https://webui.ipfs.io"]'
> ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "GET", "POST"]'

Reverting

To reset your config back to the default configuration, run the following command.

> ipfs config --json API.HTTPHeaders {}

You might also like to copy the ~/.ipfs/config file somewhere with a useful name so you can use ipfs config replace <file> to switch your node between default and dev mode easily.

Build

To create an optimized static build of the app, output to the build directory:

# Build out the html, css & jss to ./build
> npm run build

Test

The following command will run the app tests, watch source files and re-run the tests when changes are made:

> npm test

The WebUI uses Jest to run the isolated unit tests. Unit test files are located next to the component they test and have the same file name, but with the extension .test.js

End-to-end tests

The end-to-end tests (e2e) test the full app in a headless Chromium browser. They require an http server to be running to serve the app.

In dev, run npm start in another shell before starting the tests

# Run the end-to-end tests
> npm run test:e2e

By default the test run headless, so you won't see the the browser. To debug test errors, it can be helpful to see the robot clicking around the site. To disable headless mode and see the browser, set the environment variable DEBUG=true

# See the end-to-end tests in a browser
> DEBUG=true npm run test:e2e

In a continuous integration environment we lint the code, run the unit tests, build the app, start an http server and run the unit e2e tests.

> npm run lint
> npm test
> npm run build
> npm run test:ci:e2e

Coverage

To do a single run of the tests and generate a coverage report, run the following:

> npm run test:coverage

Lint

Perform standard linting on the code:

> npm run lint

Analyze

To inspect the built bundle for bundled modules and their size, first build the app then:

# Run bundle
> npm run analyze

Translations

The translations are stored on ./public/locales and the English version is the source of truth. We use Transifex to help us translate WebUI to another languages.

If you're interested in contributing a translation, go to our page on Transifex, create an account, pick a language and start translating.

You can read more on how we use Transifex and i18next in this app at docs/LOCALIZATION.md

Releasing a new version of the WebUI.

1. PR master with the result of tx pull -a to pull the latest translations from transifex
2. Tag it npm version, git push, git push --tags.
3. Add release notes to https://github.com/ipfs-shipyard/ipfs-webui/releases
4. Wait for master to build on CI, and grab the CID for the build
5. Update the hash at:
   • js-ipfs https://github.com/ipfs/js-ipfs/blob/master/src/http/api/routes/webui.js#L20
   • go-ipfs https://github.com/ipfs/go-ipfs/blob/master/core/corehttp/webui.go#L4
   • companion https://github.com/ipfs-shipyard/ipfs-companion/blob/master/add-on/src/lib/state.js#L27
   • desktop https://github.com/ipfs-shipyard/ipfs-desktop/blob/master/package.json#L17

Contribute

Feel free to dive in! Open an issue or submit PRs.

To contribute to IPFS in general, see the contributing guide.

Browser and device testing

We would like to thank BrowserStack for supporting Open Source and making it possible to test the IPFS Web UI on a wide array of operating systems and devices, improving compatibility for everyone.

License

MIT © Protocol Labs