ipfs · jessicaschilling · Apr 25, 2020 · Apr 23, 2020 · Apr 23, 2020 · Apr 23, 2020
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -258,6 +258,20 @@ module.exports = {
                   ],
                   '/how-to/browser-tools-frameworks'
                 ]
+              },
+              {
+                title: 'IPFS Companion',
+                sidebarDepth: 1,
+                collapsable: false,
+                children: [
+                  'how-to/companion-android-firefox',
+                  'how-to/companion-developer-notes',
+                  'how-to/companion-node-types',
+                  'how-to/dnslink-companion',
+                  'how-to/companion-localization',
+                  'how-to/companion-window-ipfs',
+                  '/how-to/companion-x-ipfs-path-header'
+                ]
               }
             ]
           },

diff --git a/docs/how-to/browser-tools-frameworks.md b/docs/how-to/browser-tools-frameworks.md
@@ -1,5 +1,5 @@
 ---
-title: Browser Tools and Frameworks
+title: Browser tools and frameworks
 description: Information on how to use IPFS in combination with your favorite frameworks or browser implementation tools.
 ---
 

diff --git a/docs/how-to/companion-android-firefox.md b/docs/how-to/companion-android-firefox.md
@@ -0,0 +1,66 @@
+---
+title: Use Companion on Android Firefox
+legacyUrl:
+description: Instructions for installing and using IPFS Companion on Firefox for Android.
+---
+
+# Using IPFS Companion on Firefox for Android
+
+Firefox for Android is capable of running the same extensions as the desktop version. This makes it very useful for experimenting with IPFS!
+
+## Install Firefox for Android
+
+All channels are available at Google Play Store:
+
+- [Latest stable](https://play.google.com/store/apps/details?id=org.mozilla.firefox&hl=en)
+- [Latest beta](https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta)
+- [Nightly](https://play.google.com/store/apps/details?id=org.mozilla.fennec_aurora)
+
+## Install IPFS Companion
+
+For full installation instructions, see [`README/#install`](https://github.com/ipfs-shipyard/ipfs-companion#install) in the IPFS Companion repo.
+
+You can also test the latest code locally on an emulator, or via USB on your own device. See below for details.
+
+## Hot-deploy over USB
+
+To run your extension in [Firefox for Android](https://www.mozilla.org/en-US/firefox/mobile/), follow these instructions:
+
+- [Set up your computer and Android emulator or device](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android#Set_up_your_computer_and_Android_emulator_or_device) (enable Developer Mode, USB debugging, etc.)
+
+Build everything, and switch `add-on/manifest.json` to the Fennec profile:
+
+```
+npm run dev-build
+npm run bundle:fennec
+```
+
+Then, with your device connected to your development computer, run:
+
+```
+web-ext run -s add-on --target=firefox-android
+```
+
+It will list all connected devices with their IDs. If the list is empty, go back to the setup step and try again.
+
+Next, deploy your extension to the specific device:
+
+```
+web-ext run -s add-on --target=firefox-android --android-device=<device ID>
+```
+
+The first time you run this command, there may be a popup on your Android device asking if you want to grant access over USB.
+
+## Debugging in Firefox for Android
+
+The remote debug port will be printed to the console right after successful deployment:
+
+```
+You can connect to this Android device on TCP port <debug PORT>
+```
+
+The fastest way to connect is to open `chrome://devtools/content/framework/connect/connect.xhtml` in Firefox on the same machine you run `web-ext` from.
+
+## Further resources
+
+- [MDN: Developing extensions for Firefox for Android](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android)
diff --git a/docs/how-to/companion-developer-notes.md b/docs/how-to/companion-developer-notes.md
@@ -0,0 +1,95 @@
+---
+title: Notes for developers
+legacyUrl:
+description: Developer notes for IPFS Companion, including building and running from source in Firefox, Chromium, and Android.
+---
+
+# IPFS Companion developer notes
+
+If you're looking to develop on IPFS Companion, you'll want to build from source. See the details below to get started.
+
+## Building from source
+
+You will need [NodeJS](https://nodejs.org/) and [Firefox](https://www.mozilla.org/en-US/firefox/developer/). Make sure `npm` and `firefox` are in your `PATH`.
+
+It may be a good idea to use `yarn` instead of `npm`. We provide `yarn.lock` if you choose to do so.
+
+### Installing dependencies
+
+To install all dependencies into your `node_modules` directory, execute:
+
+```bash
+npm install
+```
+
+### Build and run in Firefox
+
+You can build, test and deploy the add-on to Firefox in a single command:
+
+```bash
+npm start        # all-in-one
+```
+
+Or, if you prefer to do each step manually:
+```bash
+npm run build    # build runs bundle:firefox at the end, so manifest will be OK
+npm run test     # test suite
+npm run firefox  # spawn new Firefox
+```
+
+It is also possible to load the extension manually. Enter `about:debugging` in the URL bar, and then click "Load Temporary Add-on" and point it at `add-on/manifest.json`.
+
+### Build and manual install in Chromium
+
+First, build it manually:
+
+```bash
+npm run build bundle:chromium # last part is important: it overwrites manifest
+```
+
+Then open up `chrome://extensions` in your Chromium-based browser, enable "Developer mode", click "Load unpacked extension..." and point it at `add-on`.
+
+| Chrome "unpacked extension" | Firefox "temporary add-on" |
+|-----------------------------|----------------------------|
+| ![installing ipfs-companion as an unpacked extension in chrome](../images/ipfs-companion-install-chrome-dev.gif) | ![installing ipfs-companion as a temporary add on in firefox](../images/ipfs-companion-install-firefox-dev.gif) |
+
+
+### Firefox for Android
+
+For complete details on running Companion in Firefox for Android, see [these instructions](companion-android-firefox.md).
+
+## Useful tasks
+
+Each `npm` task can be run separately, but most of the time, `dev-build`, `test`, and `fix:lint` are all you need.
+
+- `npm install`: Install all NPM dependencies
+- `npm run build`: Build the add-on (copy external libraries, create `.zip` bundles for Chrome and Firefox)
+- `npm run bundle:chromium`: Overwrite manifest and package a generic, Chromium-compatible version
+- `npm run bundle:brave`: Overwrite manifest and package a Brave-compatible version requesting access to `chrome.sockets`
+- `npm run bundle:firefox`: Overwrite manifest and package a Firefox-compatible version
+- `npm run build:rename-artifacts`: Rename artifacts to include runtimes in filenames
+- `npm run ci`: Run tests and build (with frozen `yarn.lock`)
+- `npm test`: Run entire test suite
+- `npm run lint`: Read-only check for potential syntax problems (run all linters)
+- `npm run fix:lint`: Try to fix simple syntax problems (run `standard` with `--fix`, etc.)
+- `npm run lint:standard`: Run [Standard](http://standardjs.com) linter ([IPFS JavaScript projects default to standard code style](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md))
+- `npm run lint:web-ext`: Run [addons-linter](https://github.com/mozilla/addons-linter) shipped with `web-ext` tool
+- `npm run firefox`: Run as temporary add-on in Firefox
+- `npm run chromium`: Run as temporary add-on in Chromium
+- `npm run get-firefox-nightly`: Fetch latest Firefox nightly build to `./firefox/`
+- `npm run firefox:beta:add -- --update-link "https://host/path/to/file.xpi" file.xpi`: Add a manifest entry for new self-hosted beta for Firefox
+
+Release build shortcuts:
+- `npm run dev-build`: All-in-one: fast dependency install, build with yarn (updates yarn.lock if needed)
+- `npm run beta-build`: Reproducible beta build in docker with frozen `yarn.lock`
+- `npm run release-build`: Reproducible release build in docker with frozen `yarn.lock`
+
+## Other tips
+
+- You can switch to an alternative Firefox version by overriding your `PATH`:
+
+  ```bash
+  export PATH="/path/to/alternative/version/of/firefox/:${PATH}"
+  ```
+- [Using localization in IPFS Companion](companion-localization.md) (running browsers with specific locale, etc.)
+- [Testing persistent and restart features (Mozilla)](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Testing_persistent_and_restart_features)
diff --git a/docs/how-to/companion-localization.md b/docs/how-to/companion-localization.md
@@ -0,0 +1,41 @@
+---
+title: Use localization in Companion
+legacyUrl:
+description: Guide to running IPFS Companion with specific locales, including how to contribute translations.
+---
+
+# Localization in IPFS Companion
+
+IPFS Companion supports running in specific locales, with translations provided by the community via Transifex.
+
+## Running Chrome with a specific locale
+
+Chrome comes with locales out of the box, so it is enough to set the proper env:
+
+    LANGUAGE=pl chromium --user-data-dir=`mktemp -d`
+
+### Further resources
+- [Language Codes in Chromium Project](https://src.chromium.org/viewvc/chrome/trunk/src/third_party/cld/languages/internal/languages.cc)
+
+## Running Firefox with a specific locale
+
+Unless you've installed a locale-specific build, Firefox will have English only. If your build already has the locale you are interested in, skip step #2.
+
+1. Set `intl.locale.requested` in `about:config` or the command line via:
+   ```
+   web-ext run --pref intl.locale.requested=pl
+   ```
+2. Install your language pack from https://addons.mozilla.org/firefox/language-tools/
+3. Reload the browser extension; it should detect your new locale
+
+### Further resources
+ - [Mozilla: Use Firefox in another language](https://support.mozilla.org/en-US/kb/use-firefox-interface-other-languages-language-pack#w_how-to-change-the-language-of-the-user-interface)
+ - [Mozilla: Locale Codes](https://wiki.mozilla.org/L10n:Locale_Codes)
+
+## Contributing translations
+
+Internationalization in IPFS Companion (and all IPFS-related projects) depends on the contributions of the community. You can give back by contributing translations in your language(s)! Go to the [IPFS Companion Transifex page](https://www.transifex.com/ipfs/ipfs-companion/), send a request to join a specific language team, and start translating. You can also download raw files from Transifex, translate them in your own editor/tool and then upload them back there, but many people prefer using the simple and friendly Transifex GUI.
+
+If your language is not present in `add-on/_locales` yet, but is supported by mainstream browsers, please create a [new issue](https://github.com/ipfs/ipfs-companion/issues/new) requesting it.
+
+Don't worry if GitHub does not immediately reflect translations added at Transifex: New translations are merged manually before every release. Locale files at GitHub are often behind what is already translated at Transifex. It is a good idea to keep Transifex email notifications enabled to be notified about new strings to translate.
diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md
@@ -0,0 +1,77 @@
+---
+title: Understand Companion node types
+legacyUrl:
+description: Learn about the available node types in IPFS Companion.
+---
+
+# Understand node types in IPFS Companion
+
+![screenshot of node type switch](https://user-images.githubusercontent.com/157609/42382479-b4d98768-8134-11e8-979c-69b758846bf0.png)<br/>
+
+
+There are four available node types in IPFS Companion: external, embedded, Embedded + `chrome.sockets`, and public.
+
+**When in doubt, use the _External_ node type running on your localhost.** 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
+- If you prefer a more hands-on approach, you can ...
+  - 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 _mbedded + `chrome.sockets`_ (see below); you can always switch back to _External_ with local IPFS Desktop
+
+
+## External
+
+An _external_ node can be any instance of and IPFS daemon that runs outside of a web browser process and exposes _Gateway_ and writable _API_ over HTTP at TCP ports.
+
+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).
+
+A good practice is to run it 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)
+
+Don't know where to start? See the [command line quick-start guide](command-line-quick-start.md).
+
+
+## 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).
+
+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:
+
+- 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))
+    - 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
+
+**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
+
+###  TCP transport
+- Embedded js-ipfs is able to connect to go-ipfs
+- go-ipfs is able to connect to embedded js-ipfs
+
+### Local discovery (mDNS/DNS-SD)
+
+- Embedded node discovers go-ipfs in the LAN and automatically connects to it
+
+**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.
+
+## 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.