diff --git a/docs/BROWSERS.md b/docs/BROWSERS.md index c70c8524b6..7237c2e659 100644 --- a/docs/BROWSERS.md +++ b/docs/BROWSERS.md @@ -3,7 +3,7 @@ JS IPFS is the implementation of IPFS protocol in JavaScript. It can run on any evergreen browser, inside a service or web worker, browser extensions, Electron and in Node.js. -**This document provides key information about running JS IPFS in the browser. +**This document provides key information about running JS IPFS in the browser. Save time and get familiar with common caveats and limitations of the browser context.** ## Limitations of the Browser Context @@ -12,13 +12,13 @@ Save time and get familiar with common caveats and limitations of the browser co This means JS IPFS running in the browser is limited to Web APIs available on a web page. There is no access to raw TCP sockets nor low level UDP, only WebSockets and WebRTC. - + - Key [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) require or are restricted by [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) policies. This means JS IPFS needs to run within Secure Context (HTTPS or localhost). JS IPFS running on HTTPS website requires Secure WebSockets (TLS) and won't work with unencrypted one. [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) not being available at all. - + - [DHT](https://en.wikipedia.org/wiki/Distributed_hash_table) is not available in JS IPFS yet. [We are working on it](https://github.com/ipfs/js-ipfs/pull/1994). For now, the discovery and connectivity to other peers is achieved with a mix of rendezvous and @@ -29,7 +29,7 @@ Save time and get familiar with common caveats and limitations of the browser co We provide a few additional components useful for running JS IPFS in the browser: -- [libp2p-websocket-star](https://github.com/libp2p/js-libp2p-websocket-star/) - incorporates both a transport and a discovery service that is facilitated by the custom rendezvous server available in the repo. +- [libp2p-websocket-star](https://github.com/libp2p/js-libp2p-websocket-star/) - incorporates both a transport and a discovery service that is facilitated by the custom rendezvous server available in the repo. - Instructions on enabling `websocket-star` in js-ipfs config can be found [here](https://github.com/ipfs/js-ipfs#is-there-a-more-stable-alternative-to-webrtc-star-that-offers-a-similar-functionality). - Make sure to [run your own rendezvous server](https://github.com/libp2p/js-libp2p-websocket-star/#usage-1). - [libp2p-webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) - incorporates both a transport and a discovery service that is facilitated by the custom rendezvous server available in the repo @@ -45,12 +45,12 @@ You can find detailed information about running js-ipfs [here](https://github.co ## Best Practices - Configure nodes for using self-hosted `*-star` signaling and transport service. When in doubt, use WebSockets ones. -- Run your own instance of `*-star` signaling service. +- Run your own instance of `*-star` signaling service. The default ones are under high load and should be used only for tests and development. - Make sure content added to js-ipfs running in the browser is persisted/cached somewhere on regular IPFS daemon - Manually `pin` or preload CIDs of interest with `refs -r` beforehand. - - Preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) feature and/or - configure [delegated routing](https://github.com/ipfs/js-ipfs#configuring-delegate-routers). + - Preload content on the fly using [preload](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs/docs/MODULE.md#optionspreload) feature and/or + configure [delegated routing](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs/docs/DELEGATE_ROUTERS.md). - Avoid public instances in production environment. Make sure preload and delegate nodes used in config are self-hosted and under your control (expose a subset of go-ipfs APIs via reverse proxy such as Nginx). ## Code Examples diff --git a/docs/IPFS.md b/docs/IPFS.md deleted file mode 100644 index 8ca5ca5b3d..0000000000 --- a/docs/IPFS.md +++ /dev/null @@ -1,25 +0,0 @@ -# IPFS module - -These are functions not in the [Core API](#core-api) but that are specific to [`ipfs`](../packages/ipfs). - -## Table of contents - -- [Constructor](#constructor) - - [`options.repo`](#optionsrepo) - - [`options.repoAutoMigrate`](#optionsrepoautomigrate) - - [`options.init`](#optionsinit) - - [`options.start`](#optionsstart) - - [`options.pass`](#optionspass) - - [`options.silent`](#optionssilent) - - [`options.relay`](#optionsrelay) - - [`options.offline`](#optionsoffline) - - [`options.preload`](#optionspreload) - - [`options.EXPERIMENTAL`](#optionsexperimental) - - [`options.config`](#optionsconfig) - - [`options.ipld`](#optionsipld) - - [`options.libp2p`](#optionslibp2p) - - [`options.connectionManager`](#optionsconnectionmanager) -- [Instance methods](#instance-methods) - - [`node.start()`](#nodestart) - - [`node.stop()`](#nodestop) - diff --git a/examples/exchange-files-in-browser/public/app.js b/examples/exchange-files-in-browser/public/app.js index 590650f564..0583eb9cac 100644 --- a/examples/exchange-files-in-browser/public/app.js +++ b/examples/exchange-files-in-browser/public/app.js @@ -52,7 +52,7 @@ async function start () { Addresses: { Swarm: [ // This is a public webrtc-star server - // '/dns4/star-signal.cloud.ipfs.team/wss/p2p-webrtc-star' + // '/dns4/star-signal.cloud.ipfs.team/tcp/443/wss/p2p-webrtc-star' '/ip4/127.0.0.1/tcp/13579/wss/p2p-webrtc-star' ] }, diff --git a/packages/ipfs/README.md b/packages/ipfs/README.md index e5c4cb7bd3..1096fbf7db 100644 --- a/packages/ipfs/README.md +++ b/packages/ipfs/README.md @@ -54,9 +54,9 @@ We've come a long way, but this project is still in Alpha, lots of development i - [Browser CDN](#browser-cdn) - [Browser bundle](#browser-bundle) - [Documentation](#documentation) + - [Getting started & constructor options](#getting-started--constructor-options) - [Core API](#core-api) - [How to run IPFS in various environments](#how-to-run-ipfs-in-various-environments) - - [How to use IPFS in your application](#how-to-use-ipfs-in-your-application) - [Different topics in detail](#different-topics-in-detail) - [Questions?](#questions) - [Need help?](#need-help) @@ -107,6 +107,10 @@ Learn how to bundle IPFS into your application with webpack, parceljs and browse ## Documentation +### Getting started & constructor options + +* [docs/MODULE.md](./docs/MODULE.md) + ### Core API * [API Docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) @@ -117,10 +121,6 @@ Learn how to bundle IPFS into your application with webpack, parceljs and browse * [docs/DAEMON.md](./docs/DAEMON.md) * [docs/DOCKER.md](./docs/DOCKER.md) -### How to use IPFS in your application - -* [docs/MODULE.md](./docs/MODULE.md) - ### Different topics in detail * [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) diff --git a/packages/ipfs/docs/DELEGATE_ROUTERS.md b/packages/ipfs/docs/DELEGATE_ROUTERS.md index 2d8f83f2e4..6897cdda0f 100644 --- a/packages/ipfs/docs/DELEGATE_ROUTERS.md +++ b/packages/ipfs/docs/DELEGATE_ROUTERS.md @@ -1,5 +1,13 @@ # Configuring Delegate Routers +## What is it? + +Delegate routers peform tasks on behalf of nodes that may be missing functionality, so for example they may search the DHT for peers or content providers on behalf of IPFS implementations that do not have a DHT. + +The delegate node is started and the client of the delegate calls API methods using the IPFS HTTP API client. + +## How do I do it? + If you need to support Delegated Content and/or Peer Routing, you can enable it by specifying the multiaddrs of your delegate nodes in the config via `options.config.Addresses.Delegates`. If you need to run a delegate router we encourage you to run your own, with go-ipfs. You can see instructions for doing so in the [delegated routing example](https://github.com/libp2p/js-libp2p/tree/master/examples/delegated-routing). If you are not able to run your own delegate router nodes, we currently have two nodes that support delegated routing. **Important**: As many people may be leveraging these nodes, performance may be affected, which is why we recommend running your own nodes in production.