From 1d4af93404c657a1c7c4854a5041fe904db9b2ef Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Tue, 5 Jan 2021 13:11:04 -0700 Subject: [PATCH 01/21] Update companion-node-types.md --- docs/how-to/companion-node-types.md | 30 +++++++++++++---------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index f02203dab..c0ed0c6a9 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -5,11 +5,11 @@ description: Learn about the available node types in IPFS Companion. # Understand node types in IPFS Companion -There are four available node types in IPFS Companion: +There are four available types of node in IPFS Companion: 1. External 2. Embedded -3. Embedded + `chrome.sockets` +3. Native browser (Brave only) 4. Public ![Screenshot of node type switch](./images/node-type-switch.png) @@ -20,7 +20,8 @@ When in doubt, use the _External_ node type running on your localhost. Some opti - If you prefer a more hands-on approach: - Install IPFS by following the [command line quick-start guide](command-line-quick-start.md) - Or run it in [Docker](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker) -- If you are using [Brave](https://brave.com/), feel you may want to experiment with _embedded + `chrome.sockets`_ (see below); you can always switch back to _External_ with local IPFS Desktop + +Or, if [Brave](https://brave.com/) is your browser of choice, you can use the easiest of all these options: Just enable Brave's own built-in IPFS node. ## External @@ -41,6 +42,8 @@ Don't know where to start? See the [command line quick-start guide](command-line An _embedded_ node is a js-ipfs instance running in the browser (in-memory), without the need for any external software. It is a work in progress, but can be used for development and experimentation (e.g. for testing a dApp that uses `window.ipfs` without having to install and start up your own IPFS daemon). +For Brave users, this option isn't available in IPFS Companion preferences because it has been superceded by Brave's own [native IPFS support](#native-browser). + Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e.g. to enable experimental pubsub) via the IPFS Companion [Preferences](https://user-images.githubusercontent.com/157609/38084660-0b97c0cc-334e-11e8-9368-823345ced67f.png) **Note:** At present, embedded js-ipfs running within webextension (browser context) comes with some limitations: @@ -56,25 +59,18 @@ Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e. **When in doubt, run go-ipfs as an external node instead.** -## Embedded + `chrome.sockets` - -This node type replaces the regular _embedded_ type if the browser vendor grants us access to `chrome.sockets` APIs. These powerful APIs enable embedded js-ipfs to provide a true p2p experience without the need for an external daemon: - -### HTTP gateway - -- Access IPFS resources over HTTP without relying on a public gateway -- Automatically pick a free localhost port +### Embedded + `chrome.sockets` (deprecated) -### TCP transport +This node type has been deprecated and is no longer supported by Chromium browsers. While this option still appears in IPFS Companion preferences, users of this node type are strongly urged to migrate to a different node type ASAP. -- Embedded js-ipfs is able to connect to go-ipfs -- go-ipfs is able to connect to embedded js-ipfs +## Native browser -### Local discovery (mDNS/DNS-SD) +Users of the [Brave](https://brave.com/) browser can enable native support for IPFS using a go-ipfs node built directly into the browser itself. This is a great way to experiment with IPFS without having to install or run IPFS Desktop or an IPFS daemon. -- Embedded node discovers go-ipfs in the LAN and automatically connects to it +As with the embedded node type described above, Brave's native node is running in-memory in the browser itself, which means your node is only running when you're running your copy of Brave. However, Brave's native node offers some benefits over an embedded js-ipfs node, including: -**Note:** This is still a work in progress. see [Embedded JS-IPFS in Brave](https://github.com/ipfs-shipyard/ipfs-companion/issues/716) for the current status. +- Ability to change your preferred public gateway from Brave's settings page +- Options for default resolution of IPFS resources: via public gateway, via local node, or asking each time ## Public From 33cfd177784b347109012c561d40927764bcc9ef Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Tue, 5 Jan 2021 14:33:53 -0700 Subject: [PATCH 02/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index c0ed0c6a9..32344ff90 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -70,7 +70,7 @@ Users of the [Brave](https://brave.com/) browser can enable native support for I As with the embedded node type described above, Brave's native node is running in-memory in the browser itself, which means your node is only running when you're running your copy of Brave. However, Brave's native node offers some benefits over an embedded js-ipfs node, including: - Ability to change your preferred public gateway from Brave's settings page -- Options for default resolution of IPFS resources: via public gateway, via local node, or asking each time +- Options for default resolution of IPFS resources: through a public gateway, through a local node, or asking each time ## Public From ccbb23b01a9fb27e322086b1c162e51d7645e831 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 6 Jan 2021 16:44:55 +0100 Subject: [PATCH 03/21] docs: expand Native types License: MIT Signed-off-by: Marcin Rataj --- docs/how-to/companion-node-types.md | 54 +++++++++++++++++++---------- 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 32344ff90..836ffa963 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -5,12 +5,9 @@ description: Learn about the available node types in IPFS Companion. # Understand node types in IPFS Companion -There are four available types of node in IPFS Companion: +Available node types depend on a browser vendor, the full list is: -1. External -2. Embedded -3. Native browser (Brave only) -4. Public +[[toc]] ![Screenshot of node type switch](./images/node-type-switch.png) @@ -21,7 +18,7 @@ When in doubt, use the _External_ node type running on your localhost. Some opti - Install IPFS by following the [command line quick-start guide](command-line-quick-start.md) - Or run it in [Docker](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker) -Or, if [Brave](https://brave.com/) is your browser of choice, you can use the easiest of all these options: Just enable Brave's own built-in IPFS node. +Or, if [Brave](https://brave.com/) is your browser of choice, you can use the easiest of all these options: Just enable [Brave's own built-in IPFS node](#provided-by-brave). ## External @@ -38,11 +35,41 @@ A good practice is to run it on localhost (`127.0.0.1`), as it provides: Don't know where to start? See the [command line quick-start guide](command-line-quick-start.md). +## Native + +### Provided by Brave + +Users of the [Brave](https://brave.com/) browser can enable native support for IPFS using a go-ipfs node built directly into the browser itself. This is a great way to experiment with IPFS without having to install or run IPFS Desktop or an IPFS daemon. + +This node type brings the same benefits as [External](#external) one, with additional Brave features: + +- Native URI support: `ipfs://` and `ipns://` + - Built-in fallback to a public gateway + - Ability to change your preferred public gateway from Brave's settings page + - Options for default resolution of IPFS resources: through a public gateway, through a local node, or asking each time +- Node is managed by the browser itself + - Brave takes care of go-ipfs updates and migrations + - Node is only running when you're running your copy of Brave + - The power button in IPFS Companion menu can be used for starting and stopping the node + +::: tip Useful pages + +- `ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi` a popular URI for triggering and testing native support +- `brave://settings/extensions` one-click Companion install and URI resolution settings +- `brave://ipfs` the status of go-ipfs managed by Brave + +::: + ## Embedded -An _embedded_ node is a js-ipfs instance running in the browser (in-memory), without the need for any external software. It is a work in progress, but can be used for development and experimentation (e.g. for testing a dApp that uses `window.ipfs` without having to install and start up your own IPFS daemon). +An _embedded_ node is a js-ipfs instance running in the browser (in-memory), without the need for any external software. -For Brave users, this option isn't available in IPFS Companion preferences because it has been superceded by Brave's own [native IPFS support](#native-browser). +::: warning + +This node type is only for development and experimentation. +Regular users should use [native](#native) or [external node type](#external) instead. + +::: Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e.g. to enable experimental pubsub) via the IPFS Companion [Preferences](https://user-images.githubusercontent.com/157609/38084660-0b97c0cc-334e-11e8-9368-823345ced67f.png) @@ -57,21 +84,10 @@ Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e. - Missing relay discovery ([js-ipfs/v0.29.x/examples/circuit-relaying](https://github.com/ipfs/js-ipfs/tree/v0.29.3/examples/circuit-relaying)) - An embedded node _does not run_ when external node is selected.; every time you switch back to the embedded node, a new instance is created on-demand, and it can take a few seconds for a brand new node to find peers -**When in doubt, run go-ipfs as an external node instead.** - ### Embedded + `chrome.sockets` (deprecated) This node type has been deprecated and is no longer supported by Chromium browsers. While this option still appears in IPFS Companion preferences, users of this node type are strongly urged to migrate to a different node type ASAP. -## Native browser - -Users of the [Brave](https://brave.com/) browser can enable native support for IPFS using a go-ipfs node built directly into the browser itself. This is a great way to experiment with IPFS without having to install or run IPFS Desktop or an IPFS daemon. - -As with the embedded node type described above, Brave's native node is running in-memory in the browser itself, which means your node is only running when you're running your copy of Brave. However, Brave's native node offers some benefits over an embedded js-ipfs node, including: - -- Ability to change your preferred public gateway from Brave's settings page -- Options for default resolution of IPFS resources: through a public gateway, through a local node, or asking each time - ## Public A _public_ node is not a part of the toggle UI. It is used as an implicit fallback for its gateway functionality when an external node is offline or an embedded node is used. It does not expose the API port. From d965c0459e1b505b7fab4a233ea699abc4f53715 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Wed, 6 Jan 2021 11:26:41 -0700 Subject: [PATCH 04/21] Close-edited @lidel additions --- docs/how-to/companion-node-types.md | 61 +++++++++++++++++------------ 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 836ffa963..93e3d09b8 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -5,15 +5,15 @@ description: Learn about the available node types in IPFS Companion. # Understand node types in IPFS Companion -Available node types depend on a browser vendor, the full list is: +IPFS Companion's preferences screen allows you to choose from several different node types. The full list of available types you'll see in your Companion preferences depends on the browser you're using (i.e. Firefox, Chrome, Brave), but the full list is as follows: [[toc]] ![Screenshot of node type switch](./images/node-type-switch.png) -When in doubt, use the _External_ node type running on your localhost. Some options for doing so: +**More information on each node type is below, but when in doubt, choose the _External_ node type and run an IPFS node on your local machine.** Some options for doing so: -- Use the [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) GUI app (for Windows/Linux/Mac), which installs and manages a local IPFS node for you +- Use the [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) app (for Windows/Linux/Mac), which installs and manages a local IPFS node for you as well as offering an easy, convenient user interface for managing files, peers, and more - If you prefer a more hands-on approach: - Install IPFS by following the [command line quick-start guide](command-line-quick-start.md) - Or run it in [Docker](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker) @@ -22,52 +22,60 @@ Or, if [Brave](https://brave.com/) is your browser of choice, you can use the ea ## External -An _external_ node can be any instance of an IPFS daemon that runs outside of a web browser process and exposes _Gateway_ and writable _API_ over HTTP at TCP ports. +An _external_ node can be any instance of an IPFS daemon that: -At this time, the [go-ipfs](https://github.com/ipfs/go-ipfs) daemon is the preferred implementation. It is easier on CPU, and provides `dhtclient` mode, which -decreases ambient bandwidth use and smaller battery drain (key characteristics of something that is expected to run in the background all the time). +- Runs outside of your web browser +- Exposes a _gateway_ and writeable _API_ over HTTP at TCP ports -A good practice is to run it on localhost (`127.0.0.1`), as it provides: +At this time, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation of IPFS is the recommended choice of daemon for running an external node. It is easier on CPU than other implementations, and provides `dhtclient` mode, which decreases ambient bandwidth use and reduces battery drain (key qualities for something that is expected to run in the background all the time). + +A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it provides: - Increased security (native IPFS used as end-to-end transport) - Better UX in the browser (no mixed-content warnings) -- Improved performance (local loopback is used, no network overhead) +- Improved performance (local loopback is used, so no network overhead) + +As noted above, you can get started with running a go-ipfs node on your local machine in several ways: -Don't know where to start? See the [command line quick-start guide](command-line-quick-start.md). +- Download [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), which installs and manages a local node for you as well as offering an easy, convenient user interface for managing files, peers, and more +- If you're comfortable with the command line and don't need the convenience of the IPFS Desktop UI, follow the directions in the [command line quick-start guide](command-line-quick-start.md) +- Docker fans can run and use go-ipfs from [inside a Docker container](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker) ## Native ### Provided by Brave -Users of the [Brave](https://brave.com/) browser can enable native support for IPFS using a go-ipfs node built directly into the browser itself. This is a great way to experiment with IPFS without having to install or run IPFS Desktop or an IPFS daemon. +Users of the [Brave](https://brave.com/) browser can enable native support for IPFS using a go-ipfs node built directly into the browser itself. This is a great way to experiment with IPFS without having to install or run IPFS Desktop or the command-line daemon. -This node type brings the same benefits as [External](#external) one, with additional Brave features: +This node type offers the same benefits as an [external](#external) node, with additional features provided within Brave itself: -- Native URI support: `ipfs://` and `ipns://` +- Native support for `ipfs://` and `ipns://` URIs: - Built-in fallback to a public gateway - Ability to change your preferred public gateway from Brave's settings page - Options for default resolution of IPFS resources: through a public gateway, through a local node, or asking each time -- Node is managed by the browser itself - - Brave takes care of go-ipfs updates and migrations - - Node is only running when you're running your copy of Brave - - The power button in IPFS Companion menu can be used for starting and stopping the node +- The IPFS node is managed by Brave itself: + - Automatic go-ipfs updates and migrations + - Your node is only running when you're running your copy of Brave + - You can start/stop your Brave-based node by clicking the power button icon in IPFS Companion's main menu -::: tip Useful pages +::: tip TOOLS FOR BRAVE USERS -- `ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi` a popular URI for triggering and testing native support -- `brave://settings/extensions` one-click Companion install and URI resolution settings -- `brave://ipfs` the status of go-ipfs managed by Brave +- `ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi` + Popular URI for triggering and testing native IPFS support +- `brave://settings/extensions` + One-click Companion install and URI resolution settings +- `brave://ipfs` + Status page for Brave's built-in go-ipfs node ::: ## Embedded -An _embedded_ node is a js-ipfs instance running in the browser (in-memory), without the need for any external software. +An _embedded_ node is a js-ipfs instance running in the browser in-memory, without the need for any external software. ::: warning -This node type is only for development and experimentation. -Regular users should use [native](#native) or [external node type](#external) instead. +This node type is only for development and experimentation. Most users should use [external](#external) or [native](#native) node types instead. ::: @@ -76,8 +84,7 @@ Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e. **Note:** At present, embedded js-ipfs running within webextension (browser context) comes with some limitations: - Can't act as an HTTP gateway (extension uses public one as a fallback) -- Known to be CPU-hungry - ([#450](https://github.com/ipfs-shipyard/ipfs-companion/issues/450), [ipfs/js-ipfs#1190](https://github.com/ipfs/js-ipfs/issues/1190)) over time, which may drain your battery +- Known to be CPU-hungry ([#450](https://github.com/ipfs-shipyard/ipfs-companion/issues/450), [ipfs/js-ipfs#1190](https://github.com/ipfs/js-ipfs/issues/1190)) over time, which may drain your battery - Missing DHT ([js-ipfs/#856](https://github.com/ipfs/js-ipfs/pull/856)) - Default transports limited to websockets ([js-ipfs/#1088](https://github.com/ipfs/js-ipfs/issues/1088)) - Lack of connection closing ([ipfs/js-ipfs#962](https://github.com/ipfs/js-ipfs/issues/962)) @@ -90,4 +97,6 @@ This node type has been deprecated and is no longer supported by Chromium browse ## Public -A _public_ node is not a part of the toggle UI. It is used as an implicit fallback for its gateway functionality when an external node is offline or an embedded node is used. It does not expose the API port. +A _public_ node is used as an implicit fallback for gateway functionality when an external node is offline or an embedded node is used. It does not expose the API port. + +Because it's a fallback, it's not included as an option in Companion's preferences. From 58d671b2d9d91e9a2d12511b72723c1d3b0ae8b9 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 7 Jan 2021 16:52:40 +0100 Subject: [PATCH 05/21] Update companion-node-types.md Clarify Brave version with native IPFS --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 93e3d09b8..0be7c8943 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -45,7 +45,7 @@ As noted above, you can get started with running a go-ipfs node on your local ma ### Provided by Brave -Users of the [Brave](https://brave.com/) browser can enable native support for IPFS using a go-ipfs node built directly into the browser itself. This is a great way to experiment with IPFS without having to install or run IPFS Desktop or the command-line daemon. +Users of the [Brave](https://brave.com/) browser (v1.19 or later) can enable native support for IPFS using a go-ipfs node built directly into the browser itself. This is a great way to experiment with IPFS without having to install or run IPFS Desktop or the command-line daemon. This node type offers the same benefits as an [external](#external) node, with additional features provided within Brave itself: From e6e28d924f03fbde8c962b7bcca30540f99bc22d Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:26:05 -0700 Subject: [PATCH 06/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 0be7c8943..2e9ee61b1 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -24,8 +24,8 @@ Or, if [Brave](https://brave.com/) is your browser of choice, you can use the ea An _external_ node can be any instance of an IPFS daemon that: -- Runs outside of your web browser -- Exposes a _gateway_ and writeable _API_ over HTTP at TCP ports +- Runs outside of your web browser. +- Exposes a _gateway_ and writeable _API_ over HTTP at TCP ports. At this time, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation of IPFS is the recommended choice of daemon for running an external node. It is easier on CPU than other implementations, and provides `dhtclient` mode, which decreases ambient bandwidth use and reduces battery drain (key qualities for something that is expected to run in the background all the time). From 70cff79c1a31287ab8582afc83e395499ca05d60 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:26:11 -0700 Subject: [PATCH 07/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 2e9ee61b1..3c839cd6c 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -31,7 +31,7 @@ At this time, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation of I A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it provides: -- Increased security (native IPFS used as end-to-end transport) +- Increased security: native IPFS used as end-to-end transport. - Better UX in the browser (no mixed-content warnings) - Improved performance (local loopback is used, so no network overhead) From cc37efe04922c499c208cedfc5397ba3631aa9f7 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:27:01 -0700 Subject: [PATCH 08/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 3c839cd6c..38e8ea66d 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -33,7 +33,7 @@ A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it - Increased security: native IPFS used as end-to-end transport. - Better UX in the browser (no mixed-content warnings) -- Improved performance (local loopback is used, so no network overhead) +- Improved performance: local loopback is used, so no network overhead. As noted above, you can get started with running a go-ipfs node on your local machine in several ways: From 0c8a0a45a8246dd745929383124d7be098ff49c7 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:27:11 -0700 Subject: [PATCH 09/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 38e8ea66d..ec8b945b1 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -32,7 +32,7 @@ At this time, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation of I A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it provides: - Increased security: native IPFS used as end-to-end transport. -- Better UX in the browser (no mixed-content warnings) +- Better UX in the browser: no mixed-content warnings. - Improved performance: local loopback is used, so no network overhead. As noted above, you can get started with running a go-ipfs node on your local machine in several ways: From 35239cede5eaa5a21f98633fc1a59316ee01672f Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:27:30 -0700 Subject: [PATCH 10/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index ec8b945b1..a702b929b 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -35,7 +35,7 @@ A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it - Better UX in the browser: no mixed-content warnings. - Improved performance: local loopback is used, so no network overhead. -As noted above, you can get started with running a go-ipfs node on your local machine in several ways: +You can get started with running a go-ipfs node on your local machine in several ways: - Download [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), which installs and manages a local node for you as well as offering an easy, convenient user interface for managing files, peers, and more - If you're comfortable with the command line and don't need the convenience of the IPFS Desktop UI, follow the directions in the [command line quick-start guide](command-line-quick-start.md) From 443770952d529b5825534e30c0f016dae3586861 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:28:00 -0700 Subject: [PATCH 11/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index a702b929b..b70a632b7 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -39,7 +39,7 @@ You can get started with running a go-ipfs node on your local machine in several - Download [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), which installs and manages a local node for you as well as offering an easy, convenient user interface for managing files, peers, and more - If you're comfortable with the command line and don't need the convenience of the IPFS Desktop UI, follow the directions in the [command line quick-start guide](command-line-quick-start.md) -- Docker fans can run and use go-ipfs from [inside a Docker container](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker) +- Docker fans can run and use go-ipfs from [inside a Docker container](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker). ## Native From bb95369dbbdd6910486f049b6f33ca021735c887 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:28:15 -0700 Subject: [PATCH 12/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index b70a632b7..60171ad52 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -54,9 +54,9 @@ This node type offers the same benefits as an [external](#external) node, with a - Ability to change your preferred public gateway from Brave's settings page - Options for default resolution of IPFS resources: through a public gateway, through a local node, or asking each time - The IPFS node is managed by Brave itself: - - Automatic go-ipfs updates and migrations - - Your node is only running when you're running your copy of Brave - - You can start/stop your Brave-based node by clicking the power button icon in IPFS Companion's main menu + - Automatic go-ipfs updates and migrations. + - Your node is only running when Brave is open. + - You can start/stop your Brave-based node by clicking the power button icon in IPFS Companion's main menu. ::: tip TOOLS FOR BRAVE USERS From 399f3d54e9e86ae87c06ca6781608c011b19ea1c Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:29:28 -0700 Subject: [PATCH 13/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 60171ad52..4f0c7fb1e 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -93,7 +93,9 @@ Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e. ### Embedded + `chrome.sockets` (deprecated) -This node type has been deprecated and is no longer supported by Chromium browsers. While this option still appears in IPFS Companion preferences, users of this node type are strongly urged to migrate to a different node type ASAP. +::: warning +This node type has been deprecated and is no longer supported by Chromium browsers. While this option still appears in IPFS Companion preferences, users of this node type are strongly urged to migrate to a different node type. +::: ## Public From 1dd9dfd5860f4b2068d20b3e478feaf934be6f35 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:39:31 -0700 Subject: [PATCH 14/21] Text tweaks on top of @johnnymatthews tweaks --- docs/how-to/companion-node-types.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 4f0c7fb1e..54944cd35 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -81,15 +81,15 @@ This node type is only for development and experimentation. Most users should us Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e.g. to enable experimental pubsub) via the IPFS Companion [Preferences](https://user-images.githubusercontent.com/157609/38084660-0b97c0cc-334e-11e8-9368-823345ced67f.png) -**Note:** At present, embedded js-ipfs running within webextension (browser context) comes with some limitations: +Please note that there are some limitations when running an embedded js-ipfs instance in the browser context using Companion: -- Can't act as an HTTP gateway (extension uses public one as a fallback) -- Known to be CPU-hungry ([#450](https://github.com/ipfs-shipyard/ipfs-companion/issues/450), [ipfs/js-ipfs#1190](https://github.com/ipfs/js-ipfs/issues/1190)) over time, which may drain your battery -- Missing DHT ([js-ipfs/#856](https://github.com/ipfs/js-ipfs/pull/856)) -- Default transports limited to websockets ([js-ipfs/#1088](https://github.com/ipfs/js-ipfs/issues/1088)) +- Embedded js-ipfs cannot act as an HTTP gateway; the extension uses a public one as a fallback. +- Running an embedded js-ipfs instance is known to be CPU-hungry over time, which may drain your battery. See GitHub issues ([#450](https://github.com/ipfs-shipyard/ipfs-companion/issues/450) and [ipfs/js-ipfs#1190](https://github.com/ipfs/js-ipfs/issues/1190)) for further details +- Missing DHT (see [js-ipfs/#856](https://github.com/ipfs/js-ipfs/pull/856)). +- Default transports limited to websockets ([js-ipfs/#1088](https://github.com/ipfs/js-ipfs/issues/1088)): - Lack of connection closing ([ipfs/js-ipfs#962](https://github.com/ipfs/js-ipfs/issues/962)) - Missing relay discovery ([js-ipfs/v0.29.x/examples/circuit-relaying](https://github.com/ipfs/js-ipfs/tree/v0.29.3/examples/circuit-relaying)) -- An embedded node _does not run_ when external node is selected.; every time you switch back to the embedded node, a new instance is created on-demand, and it can take a few seconds for a brand new node to find peers +- An embedded node _does not run_ when external node is selected.; every time you switch back to the embedded node, a new instance is created on demand, and it can take a few seconds for a brand new node to find peers. ### Embedded + `chrome.sockets` (deprecated) @@ -99,6 +99,4 @@ This node type has been deprecated and is no longer supported by Chromium browse ## Public -A _public_ node is used as an implicit fallback for gateway functionality when an external node is offline or an embedded node is used. It does not expose the API port. - -Because it's a fallback, it's not included as an option in Companion's preferences. +A _public_ node is used as a fallback for gateway functionality when an external node is offline or an embedded node is used. It does not expose the API port. This type of node is not included as an option in Companion's preferences. From 5a2034eca0fbf715bf0f654bbde645947bcb7c8c Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:45:55 -0700 Subject: [PATCH 15/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 54944cd35..04fe906f1 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -27,7 +27,7 @@ An _external_ node can be any instance of an IPFS daemon that: - Runs outside of your web browser. - Exposes a _gateway_ and writeable _API_ over HTTP at TCP ports. -At this time, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation of IPFS is the recommended choice of daemon for running an external node. It is easier on CPU than other implementations, and provides `dhtclient` mode, which decreases ambient bandwidth use and reduces battery drain (key qualities for something that is expected to run in the background all the time). +The [go-ipfs](https://github.com/ipfs/go-ipfs) implementation of IPFS is the recommended choice for running an external IPFS node. It's less power-hungry than other implementations and uses the `dhtclient` mode to decrease ambient bandwidth use and reduce battery drain. A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it provides: From abf4578cc80a8fc10d1068793639b260a57edc04 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:46:23 -0700 Subject: [PATCH 16/21] More text tweaks from @johnnymatthews suggestions --- docs/how-to/companion-node-types.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 54944cd35..35b285bfc 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -5,7 +5,7 @@ description: Learn about the available node types in IPFS Companion. # Understand node types in IPFS Companion -IPFS Companion's preferences screen allows you to choose from several different node types. The full list of available types you'll see in your Companion preferences depends on the browser you're using (i.e. Firefox, Chrome, Brave), but the full list is as follows: +IPFS Companion's preferences screen allows you to choose from several different node types. The available types you'll see in your Companion preferences depends on the browser you're using (i.e. Firefox, Chrome, Brave), but the full list is as follows: [[toc]] @@ -89,7 +89,7 @@ Please note that there are some limitations when running an embedded js-ipfs ins - Default transports limited to websockets ([js-ipfs/#1088](https://github.com/ipfs/js-ipfs/issues/1088)): - Lack of connection closing ([ipfs/js-ipfs#962](https://github.com/ipfs/js-ipfs/issues/962)) - Missing relay discovery ([js-ipfs/v0.29.x/examples/circuit-relaying](https://github.com/ipfs/js-ipfs/tree/v0.29.3/examples/circuit-relaying)) -- An embedded node _does not run_ when external node is selected.; every time you switch back to the embedded node, a new instance is created on demand, and it can take a few seconds for a brand new node to find peers. +- An embedded node _does not run_ when an external node is selected; every time you switch back to the embedded node, a new instance is created on demand, and it can take a few seconds for a newly running node to find peers. ### Embedded + `chrome.sockets` (deprecated) From 253ced2e23512f64964efd4e72be11909954a02a Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:48:28 -0700 Subject: [PATCH 17/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 16e8ddd14..a1c2b2ba0 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -37,7 +37,7 @@ A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it You can get started with running a go-ipfs node on your local machine in several ways: -- Download [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), which installs and manages a local node for you as well as offering an easy, convenient user interface for managing files, peers, and more +- [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) installs and manages a local node for you, as well as offering an easy, convenient user interface for managing files and peers. - If you're comfortable with the command line and don't need the convenience of the IPFS Desktop UI, follow the directions in the [command line quick-start guide](command-line-quick-start.md) - Docker fans can run and use go-ipfs from [inside a Docker container](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker). From cd6dce8da265cc79159093b7077a2fc0b90ff284 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:48:38 -0700 Subject: [PATCH 18/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index a1c2b2ba0..d7c162d53 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -38,7 +38,7 @@ A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it You can get started with running a go-ipfs node on your local machine in several ways: - [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) installs and manages a local node for you, as well as offering an easy, convenient user interface for managing files and peers. -- If you're comfortable with the command line and don't need the convenience of the IPFS Desktop UI, follow the directions in the [command line quick-start guide](command-line-quick-start.md) +- If you're comfortable with the command line and don't need the convenience of the IPFS Desktop UI, follow the directions in the [command line quick-start guide](/how-to/command-line-quick-start/). - Docker fans can run and use go-ipfs from [inside a Docker container](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker). ## Native From 37adc3935eecc3cf606de48a2c138018fa2dbf4b Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:49:20 -0700 Subject: [PATCH 19/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index d7c162d53..eb5868980 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -50,9 +50,9 @@ Users of the [Brave](https://brave.com/) browser (v1.19 or later) can enable nat This node type offers the same benefits as an [external](#external) node, with additional features provided within Brave itself: - Native support for `ipfs://` and `ipns://` URIs: - - Built-in fallback to a public gateway - - Ability to change your preferred public gateway from Brave's settings page - - Options for default resolution of IPFS resources: through a public gateway, through a local node, or asking each time + - Built-in fallback to a public gateway. + - Ability to change your preferred public gateway from Brave's settings page. + - Options for default resolution of IPFS resources: through a public gateway, through a local node, or asking each time. - The IPFS node is managed by Brave itself: - Automatic go-ipfs updates and migrations. - Your node is only running when Brave is open. From 7031468ad9678c739492cbf51bf8af1332e90adb Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 09:51:09 -0700 Subject: [PATCH 20/21] Update docs/how-to/companion-node-types.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/companion-node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index eb5868980..6712bd057 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -11,7 +11,7 @@ IPFS Companion's preferences screen allows you to choose from several different ![Screenshot of node type switch](./images/node-type-switch.png) -**More information on each node type is below, but when in doubt, choose the _External_ node type and run an IPFS node on your local machine.** Some options for doing so: +If you have an IPFS node installed but don't know which Companion node type to chose, select _External_. If you do not have an IPFS node installed, [see the installation section](/install) to find out how to install one. If you'd prefer not to install an IPFS node, consider using either the [native](#native) or [embedded](#embedded) modes. - Use the [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) app (for Windows/Linux/Mac), which installs and manages a local IPFS node for you as well as offering an easy, convenient user interface for managing files, peers, and more - If you prefer a more hands-on approach: From d1ea32ce9318de7127f85a8158685b68ffc4cdd7 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 7 Jan 2021 10:07:55 -0700 Subject: [PATCH 21/21] Streamline initial guidance tree per @johnnymatthews --- docs/how-to/companion-node-types.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md index 6712bd057..cb9f7e2e1 100644 --- a/docs/how-to/companion-node-types.md +++ b/docs/how-to/companion-node-types.md @@ -9,16 +9,12 @@ IPFS Companion's preferences screen allows you to choose from several different [[toc]] -![Screenshot of node type switch](./images/node-type-switch.png) +![Screenshot of node type selector in Companion preferences](./images/node-type-switch.png) -If you have an IPFS node installed but don't know which Companion node type to chose, select _External_. If you do not have an IPFS node installed, [see the installation section](/install) to find out how to install one. If you'd prefer not to install an IPFS node, consider using either the [native](#native) or [embedded](#embedded) modes. +**If you're already running a local IPFS node, choose _External_.** If not, do one of the following: -- Use the [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) app (for Windows/Linux/Mac), which installs and manages a local IPFS node for you as well as offering an easy, convenient user interface for managing files, peers, and more -- If you prefer a more hands-on approach: - - Install IPFS by following the [command line quick-start guide](command-line-quick-start.md) - - Or run it in [Docker](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker) - -Or, if [Brave](https://brave.com/) is your browser of choice, you can use the easiest of all these options: Just enable [Brave's own built-in IPFS node](#provided-by-brave). +- [Install](/install) and run IPFS as an [external node](#external) (recommended). +- Use a [native node](#native) built into your browser (Brave v1.19 or later only) or the [embedded node](#embedded) built into Companion. ## External