docs: getting started #514

vasco-santos · 2019-12-12T16:36:44Z

This getting started doc aims to be the entry point for new users of js-libp2p since it goes deeper in detail within each concept.

For more advanced users, we expect that they consult the API and CONFIG docs mostly, as they are more straightforward documents

vasco-santos · 2019-12-13T14:47:56Z

cc @terichadbourne

jacobheun

@vasco-santos I created a PR to discuss some edits, #520. I think it might be easier to do it that way than individual comments across this PR for the larger changes. I only did the first bit of configuration so we can discuss the approach.

A few thoughts:

I think reducing the amount of text for each section would be helpful. If we can succinctly describe each step and then link off to further reading, I think that might be easier for folks to consume.
I think it would be good to have the final code of this in ./examples. If anyone gets stuck, they can go reference the example code and we can more easily ensure this is running properly in future releases, as we test all examples.
While multiplexing is not required, we should have it in the basic setup. If it's not configured the node won't be able to speak to the main network. The majority of users will likely need multiplexing. For me, basic setup means I should be able to start talking with the main network, even if it's in a limited fashion.

vasco-santos · 2019-12-18T11:20:50Z

I think it would be good to have the final code of this in ./examples. If anyone gets stuck, they can go reference the example code and we can more easily ensure this is running properly in future releases, as we test all examples.

👍

While multiplexing is not required, we should have it in the basic setup. If it's not configured the node won't be able to speak to the main network. The majority of users will likely need multiplexing. For me, basic setup means I should be able to start talking with the main network, even if it's in a limited fashion.

sounds good, I will change that once we get #520 here

vasco-santos · 2019-12-30T16:47:59Z

I think I addressed all the feedback except for:

I think it would be good to have the final code of this in ./examples. If anyone gets stuck, they can go reference the example code and we can more easily ensure this is running properly in future releases, as we test all examples.

For that one in specific, I will create an issue to track all the remaining endeavours. I want to get all the examples being tested in CI, in order to ease the release process

doc/GETTING_STARTED.md

jacobheun · 2020-01-16T10:18:10Z

doc/GETTING_STARTED.md

+
+You can install `libp2p-mplex` and add it to your libp2p node as follows in the next example. You should revisit the [API](./API.md) document, more specifically [API#dial](./API.md#dial) and [API#handle](./API.md#handle).
+
+We will also install the next dependencies for easily work with [async iterable duplex streams](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9).


We should point to the local README we have for this, as we'll also be including more examples of using iterable streams in libp2p https://github.com/libp2p/js-libp2p/blob/refactor/async-await/doc/STREAMING_ITERABLES.md

doc/GETTING_STARTED.md

jacobheun · 2020-01-16T13:15:42Z

doc/GETTING_STARTED.md

+await node.stop()
+```
+
+If you are not familiar with multiaddrs, you should read the [multiformats/js-multiaddr](https://github.com/multiformats/js-multiaddr) README.


This seems out of place, not sure where this should go.

I think we can just remove it

doc/GETTING_STARTED.md

jacobheun · 2020-01-16T13:41:30Z

doc/GETTING_STARTED.md

+npm install libp2p-kad-dht
+```
+
+`js-libp2p` configuration is not well defined yet regarding content routing routing. Therefore, the `dht` should be plugged through a `modules.dht` property, while the `libp2p-delegated-content-routing` should be plugged into `modules.contentRouting` array.


Same here, it is defined, but the DHT does not yet conform to the separate configuration.

jacobheun · 2020-01-16T13:44:46Z

doc/GETTING_STARTED.md

+await node.start()
+
+// provide cid
+await libp2p.contentRouting.provide(cid)


Since we're aiming to have people join the live network we should probably not have them provide content, as their node is going to go offline pretty quickly. What do you think?

For findProviders we should just use a well known cid, and we should include the cid module here. A website or the ipfs readme might be good options.

doc/GETTING_STARTED.md

jacobheun · 2020-01-16T13:50:10Z

doc/GETTING_STARTED.md

+
+const node = await Libp2p.create({
+  modules: {
+    transport: [TCP],


Same thing here, why the switch to TCP?

* doc: initial review of getting started Co-Authored-By: Vasco Santos <[email protected]>

Co-Authored-By: Jacob Heun <[email protected]>

jacobheun · 2020-01-22T13:02:40Z

I went ahead and cleaned up some of the language. I also removed mdns, DHT and Pubsub setup from the guide for now. The problem with having these included is that the setup as it was, wasn't sufficient for these things to work properly. For example, you could start and run pubsub, but you wouldn't be publishing to anything. I think it's more valuable to get people running a node and connecting it to the public network, and then referencing the Configuration readme and examples folder for additional sources of configuration. The examples do a better job of ensuring each piece will yield results by doing things like running multiple nodes when necessary.

I think we can add additional components to this in the future, but they should work without needing any additional configuration/resources.

README.md

doc/API.md

alanshaw · 2020-01-23T12:01:40Z

doc/API.md

+
+- `peer`: instance of [PeerInfo][https://github.com/libp2p/js-peer-info]
+
+#### We have a new connection to a peer


Suggested change

#### We have a new connection to a peer

#### An incoming connection from a peer has been established

Is it only incoming or outgoing also?

It is both.

Gotcha, might be an idea just to be explicit that it is!

doc/API.md

doc/CONFIGURATION.md

doc/GETTING_STARTED.md

alanshaw · 2020-01-23T12:10:17Z

doc/GETTING_STARTED.md

+
+#### Transports
+
+Libp2p uses Transports to establish connections between peers over the network. You can configure any number of Transports, but you only need 1 to start with. Supporting more Transports will improve the ability of your node to speak to a larger number of nodes on the network.


Could we explain a little what a transport is?

doc/GETTING_STARTED.md

Co-Authored-By: Alan Shaw <[email protected]>

* docs: getting started * docs: review getting started (#520) * doc: initial review of getting started Co-Authored-By: Vasco Santos <[email protected]> * chore: move multiplexing to basic setup * chore: add read more cta * chore: apply suggestions from code review Co-Authored-By: Jacob Heun <[email protected]> * chore: just configure multiplexer * chore: apply suggestions from code review Co-Authored-By: Jacob Heun <[email protected]> * chore: just use websockets and changed dht module introduction * chore: add reference for events in the API doc * docs: simplify getting started guide and clean up language * chore: apply suggestions from code review Co-Authored-By: Alan Shaw <[email protected]> * docs(fix): address review comments Co-authored-by: Jacob Heun <[email protected]> Co-authored-by: Alan Shaw <[email protected]>

vasco-santos force-pushed the docs/getting-started branch 3 times, most recently from 8dc4726 to 570da2a Compare December 13, 2019 13:53

vasco-santos marked this pull request as ready for review December 13, 2019 14:00

vasco-santos requested review from jacobheun and yusefnapora December 13, 2019 14:00

jacobheun mentioned this pull request Dec 16, 2019

docs: review getting started #520

Merged

jacobheun reviewed Dec 16, 2019

View reviewed changes

vasco-santos force-pushed the docs/getting-started branch from 3a63a7f to 1a72e46 Compare December 30, 2019 16:47

jacobheun reviewed Jan 16, 2020

View reviewed changes

vasco-santos requested a review from jacobheun January 16, 2020 14:57

vasco-santos and others added 10 commits January 22, 2020 12:10

docs: getting started

c451bbc

docs: review getting started (#520)

a7df767

* doc: initial review of getting started Co-Authored-By: Vasco Santos <[email protected]>

chore: move multiplexing to basic setup

7a08448

chore: add read more cta

53dc00b

chore: apply suggestions from code review

c3a1785

Co-Authored-By: Jacob Heun <[email protected]>

chore: just configure multiplexer

5484df9

chore: apply suggestions from code review

b8cc237

Co-Authored-By: Jacob Heun <[email protected]>

chore: just use websockets and changed dht module introduction

cfd2e41

chore: add reference for events in the API doc

7cb9a51

docs: simplify getting started guide and clean up language

462d303

jacobheun force-pushed the docs/getting-started branch from e437c0a to 462d303 Compare January 22, 2020 12:55

jacobheun requested review from alanshaw and dirkmc January 22, 2020 13:03

alanshaw suggested changes Jan 23, 2020

View reviewed changes

jacobheun and others added 2 commits January 23, 2020 14:04

chore: apply suggestions from code review

9ea15b3

Co-Authored-By: Alan Shaw <[email protected]>

docs(fix): address review comments

381c61f

jacobheun requested a review from alanshaw January 23, 2020 14:28

jacobheun mentioned this pull request Jan 23, 2020

refactor: update network to use async libp2p ipfs/js-ipfs-bitswap#206

Merged

1 task

jacobheun removed their request for review January 23, 2020 14:54

alanshaw approved these changes Jan 23, 2020

View reviewed changes

jacobheun merged commit 461faca into refactor/async-await Jan 23, 2020

jacobheun deleted the docs/getting-started branch January 23, 2020 16:12


		You can install `libp2p-mplex` and add it to your libp2p node as follows in the next example. You should revisit the [API](./API.md) document, more specifically [API#dial](./API.md#dial) and [API#handle](./API.md#handle).

		We will also install the next dependencies for easily work with [async iterable duplex streams](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9).


		- `peer`: instance of [PeerInfo][https://github.com/libp2p/js-peer-info]

		#### We have a new connection to a peer

	#### We have a new connection to a peer
	#### An incoming connection from a peer has been established


		#### Transports

		Libp2p uses Transports to establish connections between peers over the network. You can configure any number of Transports, but you only need 1 to start with. Supporting more Transports will improve the ability of your node to speak to a larger number of nodes on the network.

docs: getting started #514

docs: getting started #514

Uh oh!

Conversation

vasco-santos commented Dec 12, 2019

Uh oh!

vasco-santos commented Dec 13, 2019

Uh oh!

jacobheun left a comment

Choose a reason for hiding this comment

Uh oh!

vasco-santos commented Dec 18, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vasco-santos commented Dec 30, 2019

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacobheun commented Jan 22, 2020

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vasco-santos commented Dec 18, 2019 •

edited

Loading