From 272096676349f3e11f5f8a007aa3dc6ab4823b5a Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Thu, 12 Nov 2020 12:01:47 +0100 Subject: [PATCH 1/5] docs: production guide setup --- doc/production/CIRCUIT_RELAY.md | 3 +++ doc/production/DELEGATE_NODES.md | 3 +++ doc/production/README.md | 38 ++++++++++++++++++++++++++++++++ 3 files changed, 44 insertions(+) create mode 100644 doc/production/CIRCUIT_RELAY.md create mode 100644 doc/production/DELEGATE_NODES.md create mode 100644 doc/production/README.md diff --git a/doc/production/CIRCUIT_RELAY.md b/doc/production/CIRCUIT_RELAY.md new file mode 100644 index 0000000000..dc09050212 --- /dev/null +++ b/doc/production/CIRCUIT_RELAY.md @@ -0,0 +1,3 @@ +# Circuit Relay + +TODO \ No newline at end of file diff --git a/doc/production/DELEGATE_NODES.md b/doc/production/DELEGATE_NODES.md new file mode 100644 index 0000000000..6fad24f0e8 --- /dev/null +++ b/doc/production/DELEGATE_NODES.md @@ -0,0 +1,3 @@ +# Delegate Nodes + +[TODO](https://github.com/libp2p/js-libp2p/pull/718) diff --git a/doc/production/README.md b/doc/production/README.md new file mode 100644 index 0000000000..af2b4ce61f --- /dev/null +++ b/doc/production/README.md @@ -0,0 +1,38 @@ +# Production + +Nowadays, you can run JavaScript code in several different environments, some of them with their own particularities. Moreover, you can use `js-libp2p` for a wide range of use cases. Different environments and different use cases mean different configurations and challenges in the network. + +Libp2p nodes can vary from nodes behind an application, to infrastructure nodes that enable the network to operate and to be efficient. In this context, the Libp2p project provides public infrastructure to boost the network, enable nodes connectivity and improve constrained nodes performance. This public infrastructure should be leveraged for learning the concepts and experimenting. When an application on top of libp2p aims to move into production, its own infrastructure should be setup as the public nodes will be intensively used by others and its availability is not guaranteed. + +This guide aims to guide you from using the public infrastructure into setting up your own. + +## Table of Contents + +* [Production](#production) + * [Star servers](#star-servers) + * [Delegate nodes](#delegate-nodes) + * [Circuit Relay](#circuit-relay) + +## `webrtc-star` servers + +While the libp2p core codebase aims to work in multiple environments, there are some limitations that are not possible to overcome at the time of writing. Regarding `webRTC`, at the time of writing a set of star servers are needed to act as a rendezvous point, where peers can learn about other peers (`peer-discovery`), as well as exchange their SDP offers (signaling data). + +You can read on how to setup your own set of delegated nodes in [libp2p/js-libp2p-webrtc-star/DEPLOYMENT.md](https://github.com/libp2p/js-libp2p-webrtc-star/blob/master/DEPLOYMENT.md). + +It is worth pointing out that with new discovery protocols on the way, as well as support for distributed signaling, the star servers should be deprecated on the long run. + +## Delegate nodes + +Libp2p nodes in scenarios such as browser environment and constrained devices will not be an efficient node in the libp2p DHT overlay, as a consequence of their known limitations regarding connectivity and performance. + +Aiming to support these type of nodes to find other peers and content in the network, delegate nodes can be setup. With a set of well known libp2p delegate nodes, nodes with limitations in the network can leverage them to perform peer and content routing calls. + +You can read on how to setup your own set of delegated nodes in [DELEGATE_NODES.md](./DELEGATE_NODES.md). + +## Circuit Relay + +Libp2p nodes acting as circuit relay aim to establish connectivity between libp2p nodes (e.g. IPFS nodes) that wouldn't otherwise be able to establish a direct connection to each other. + +A relay is needed in situations where nodes are behind NAT, reverse proxies, firewalls and/or simply don't support the same transports (e.g. go-libp2p vs. browser-libp2p). The circuit relay protocol exists to overcome those scenarios. Nodes with the `auto-relay` feature enabled can automatically bind themselves on a relay to listen for connections on their behalf. + +You can read on how to setup your own set of delegated nodes in [CIRCUIT_RELAY.md](./CIRCUIT_RELAY.md). From d461414b5aef74e43b6f454e57570b7bc765a1b3 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Fri, 27 Nov 2020 15:09:36 +0100 Subject: [PATCH 2/5] docs: production guide relay --- doc/production/CIRCUIT_RELAY.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/production/CIRCUIT_RELAY.md b/doc/production/CIRCUIT_RELAY.md index dc09050212..400befb56f 100644 --- a/doc/production/CIRCUIT_RELAY.md +++ b/doc/production/CIRCUIT_RELAY.md @@ -1,3 +1,7 @@ # Circuit Relay -TODO \ No newline at end of file +> Circuit Switching for libp2p, also known as TURN or Relay in Networking literature. + +If you are looking for information about libp2p's circuit relay, you should read its [spec](https://github.com/libp2p/specs/tree/master/relay). + + From dec3de520ac332199b2f95af95825e6c085f1f3d Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Mon, 30 Nov 2020 15:28:12 +0100 Subject: [PATCH 3/5] chore: add relay --- doc/production/CIRCUIT_RELAY.md | 7 ------- doc/production/README.md | 2 +- 2 files changed, 1 insertion(+), 8 deletions(-) delete mode 100644 doc/production/CIRCUIT_RELAY.md diff --git a/doc/production/CIRCUIT_RELAY.md b/doc/production/CIRCUIT_RELAY.md deleted file mode 100644 index 400befb56f..0000000000 --- a/doc/production/CIRCUIT_RELAY.md +++ /dev/null @@ -1,7 +0,0 @@ -# Circuit Relay - -> Circuit Switching for libp2p, also known as TURN or Relay in Networking literature. - -If you are looking for information about libp2p's circuit relay, you should read its [spec](https://github.com/libp2p/specs/tree/master/relay). - - diff --git a/doc/production/README.md b/doc/production/README.md index af2b4ce61f..76fe39a406 100644 --- a/doc/production/README.md +++ b/doc/production/README.md @@ -35,4 +35,4 @@ Libp2p nodes acting as circuit relay aim to establish connectivity between libp2 A relay is needed in situations where nodes are behind NAT, reverse proxies, firewalls and/or simply don't support the same transports (e.g. go-libp2p vs. browser-libp2p). The circuit relay protocol exists to overcome those scenarios. Nodes with the `auto-relay` feature enabled can automatically bind themselves on a relay to listen for connections on their behalf. -You can read on how to setup your own set of delegated nodes in [CIRCUIT_RELAY.md](./CIRCUIT_RELAY.md). +You can use [libp2p/js-libp2p-hop-relay-server](https://github.com/libp2p/js-libp2p-hop-relay-server) to setup your own relay server. This also includes an easy to customize Docker setup for a HOP Relay. From f324d057e633ed45c8d83e1a2130767df9ee28bf Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Fri, 4 Dec 2020 10:32:39 +0100 Subject: [PATCH 4/5] docs: add ssl section to production guide --- doc/production/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/production/README.md b/doc/production/README.md index 76fe39a406..5b188e2517 100644 --- a/doc/production/README.md +++ b/doc/production/README.md @@ -12,6 +12,7 @@ This guide aims to guide you from using the public infrastructure into setting u * [Star servers](#star-servers) * [Delegate nodes](#delegate-nodes) * [Circuit Relay](#circuit-relay) + * [SSL](#ssl) ## `webrtc-star` servers @@ -36,3 +37,7 @@ Libp2p nodes acting as circuit relay aim to establish connectivity between libp2 A relay is needed in situations where nodes are behind NAT, reverse proxies, firewalls and/or simply don't support the same transports (e.g. go-libp2p vs. browser-libp2p). The circuit relay protocol exists to overcome those scenarios. Nodes with the `auto-relay` feature enabled can automatically bind themselves on a relay to listen for connections on their behalf. You can use [libp2p/js-libp2p-hop-relay-server](https://github.com/libp2p/js-libp2p-hop-relay-server) to setup your own relay server. This also includes an easy to customize Docker setup for a HOP Relay. + +## SSL + +TODO From 5660d8fdae799095c9756cfbaa68eb8446b59c06 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Fri, 4 Dec 2020 15:43:05 +0100 Subject: [PATCH 5/5] chore: restructure doc per feedback --- doc/production/README.md | 50 +++++++++++++++++++++++++++++----------- 1 file changed, 36 insertions(+), 14 deletions(-) diff --git a/doc/production/README.md b/doc/production/README.md index 5b188e2517..e655d0b6ff 100644 --- a/doc/production/README.md +++ b/doc/production/README.md @@ -8,36 +8,58 @@ This guide aims to guide you from using the public infrastructure into setting u ## Table of Contents -* [Production](#production) - * [Star servers](#star-servers) - * [Delegate nodes](#delegate-nodes) +* [Joining the Network](#joining-the-network) +* [Connecting to Nodes with connectivity limitations](#connecting-to-nodes-with-connectivity-limitations) + * [`webrtc-star` servers](#webrtc-star-servers) * [Circuit Relay](#circuit-relay) +* [Querying the network from the browser](#querying-the-network-from-the-browser) +* [Others](#others) * [SSL](#ssl) -## `webrtc-star` servers +## Joining the Network -While the libp2p core codebase aims to work in multiple environments, there are some limitations that are not possible to overcome at the time of writing. Regarding `webRTC`, at the time of writing a set of star servers are needed to act as a rendezvous point, where peers can learn about other peers (`peer-discovery`), as well as exchange their SDP offers (signaling data). +Once a libp2p node stars, it will need to connect to a set of peers in order to establish its overlay network. -You can read on how to setup your own set of delegated nodes in [libp2p/js-libp2p-webrtc-star/DEPLOYMENT.md](https://github.com/libp2p/js-libp2p-webrtc-star/blob/master/DEPLOYMENT.md). +Currently `js-libp2p` is not the best choice for being a bootstrap node. Its DHT needs to be improved, in order to become an effective server to enable other nodes to properly bootstrap their network. -It is worth pointing out that with new discovery protocols on the way, as well as support for distributed signaling, the star servers should be deprecated on the long run. +Setting up a fleet of [`go-libp2p`](https://github.com/libp2p/go-libp2p) nodes is the recommended way to proceed here. -## Delegate nodes +## Connecting to Nodes with connectivity limitations -Libp2p nodes in scenarios such as browser environment and constrained devices will not be an efficient node in the libp2p DHT overlay, as a consequence of their known limitations regarding connectivity and performance. +While the libp2p core codebase aims to work in multiple environments, there are some limitations that are not possible to overcome at the time of writing. These limitations include browser nodes, nodes behind NAT, reverse proxies, firewalls, or lack of compatible transports. -Aiming to support these type of nodes to find other peers and content in the network, delegate nodes can be setup. With a set of well known libp2p delegate nodes, nodes with limitations in the network can leverage them to perform peer and content routing calls. +In the browser, libp2p supports two transports: `websockets` and `webrtc-star`. Nowadays, browsers do not support listening for connections, but only to dial known addresses. `webrtc-star` servers can be used to enable libp2p nodes to discover other nodes running on the browser and to help them establish a connection. -You can read on how to setup your own set of delegated nodes in [DELEGATE_NODES.md](./DELEGATE_NODES.md). +For nodes that cannot be dialed (including browser), circuit relay nodes should be used. + +### `webrtc-star` servers + +Regarding `webRTC` connections, a set of star servers are needed to act as a rendezvous point, where peers can learn about other peers (`peer-discovery`), as well as exchange their SDP offers (signaling data). + +You can read on how to setup your own star servers in [libp2p/js-libp2p-webrtc-star/DEPLOYMENT.md](https://github.com/libp2p/js-libp2p-webrtc-star/blob/master/DEPLOYMENT.md). + +It is worth pointing out that with new discovery protocols on the way, as well as support for distributed signaling, the star servers should be deprecated on the long run. -## Circuit Relay +### Circuit Relay Libp2p nodes acting as circuit relay aim to establish connectivity between libp2p nodes (e.g. IPFS nodes) that wouldn't otherwise be able to establish a direct connection to each other. A relay is needed in situations where nodes are behind NAT, reverse proxies, firewalls and/or simply don't support the same transports (e.g. go-libp2p vs. browser-libp2p). The circuit relay protocol exists to overcome those scenarios. Nodes with the `auto-relay` feature enabled can automatically bind themselves on a relay to listen for connections on their behalf. -You can use [libp2p/js-libp2p-hop-relay-server](https://github.com/libp2p/js-libp2p-hop-relay-server) to setup your own relay server. This also includes an easy to customize Docker setup for a HOP Relay. +You can use [libp2p/js-libp2p-relay-server](https://github.com/libp2p/js-libp2p-relay-server) to setup your own relay server. This also includes an easy to customize Docker setup for a HOP Relay. + +## Querying the network from the browser + +Libp2p nodes in scenarios such as browser environment and constrained devices will not be an efficient node in the libp2p DHT overlay, as a consequence of their known limitations regarding connectivity and performance. + +Aiming to support these type of nodes to find other peers and content in the network, delegate nodes can be setup. With a set of well known IPFS delegate nodes, nodes with limitations in the network can leverage them to perform peer and content routing queries. + +Currently, delegate nodes must be IPFS nodes as the IPFS HTTP API is leveraged by them to make routing queries. + +You can read on how to setup your own set of delegated nodes in [DELEGATE_NODES.md](./DELEGATE_NODES.md). + +## Others -## SSL +### SSL TODO