From 0dc2de7372e8e37093c97442df76b9059fa1d3ca Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 22 Oct 2020 13:18:27 -0600 Subject: [PATCH] feat: rework readme (#1703) * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Create DEVELOPER-NOTES.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Everything but Features is better now * Add primary screenshot * Update README.md * Update README.md * Update README.md * Add screenshots * Last tweaks before review * Update README.md Co-authored-by: Marcin Rataj * Update README.md Co-authored-by: Marcin Rataj * Update README.md Co-authored-by: Marcin Rataj * Update README.md Co-authored-by: Marcin Rataj * Update README.md Co-authored-by: Marcin Rataj * Update README.md Co-authored-by: Marcin Rataj * One more round of copy edits Co-authored-by: Marcin Rataj --- DEVELOPER-NOTES.md | 49 ++++++++ README.md | 274 ++++++++++++++++++++++----------------------- 2 files changed, 184 insertions(+), 139 deletions(-) create mode 100644 DEVELOPER-NOTES.md diff --git a/DEVELOPER-NOTES.md b/DEVELOPER-NOTES.md new file mode 100644 index 000000000..01528093b --- /dev/null +++ b/DEVELOPER-NOTES.md @@ -0,0 +1,49 @@ +# Developer notes + +Below are helpful notes for developers hacking on or releasing new versions of IPFS Desktop. + +## Release checklist + +Before cutting a new release of IPFS Desktop, please go through the following process: + +### Manual testing + +Manually test a few things that don't transfer well to automated testing: + +1. **Mac/Windows/Linux:** Confirm that "Take Screenshot" under the menubar/system tray menu works as expected for both single- and multi-monitor setups: + - File(s) import correctly + - Correct link is copied to clipboard +2. **Mac only:** Drag/drop onto menubar icon behaves as expected when dragging one file, several files, and a combination of files/folders: + - File(s) import correctly + - Correct link is copied to clipboard +3. **Windows only:** Right-click on a file and "Add to IPFS" from context menu works as expected: + - File(s) import correctly + - Correct link is copied to clipboard +4. **Mac/Windows:** Confirm that OS-wide protocol handler was registered by opening `ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi` in a user agent _without_ IPFS Companion + +### Main release process +1. Fetch new translations from Transifex: `tx pull -a`. +2. Commit the changes. +3. Bump the version in `package.json`. +4. Commit the changes. +5. Create a tag with the same version as your bump: `git tag vA.B.C`. +6. Publish local changes and the tag to the GitHub repo: `git push && git push origin vA.B.C`. +7. Wait for the CI to upload the binaries to the draft release (a new one will be created if you haven't drafted one). +8. Publish a release draft. + - Once a release is published, users should receive the app update (see https://www.electron.build/auto-update for details). + - The `latest.yml, latest-mac.yml, latest-linux.yml` files on the release are used by the app to determine when an app update is available. +9. Update all links and badges in `README.md` to point to the new version (`A.B.C`). +10. Update `CHANGELOG.md` with details from release/release draft. +11. Update selected package managers: + - Wait for CI to finish and confirm that it updated [Snap](https://snapcraft.io/ipfs-desktop), and is at least pending review on [Chocolatey](https://chocolatey.org/packages/ipfs-desktop#versionhistory). + - Update the [Homebrew cask](https://github.com/Homebrew/homebrew-cask/blob/master/CONTRIBUTING.md#updating-a-cask). +12. To start work on the next version, bump the version in `package.json`. + +### Manually notarize `.dmg` with Apple + +These steps are only needed as a fallback if CI is not correctly notarizing the `.dmg` file. For context, see [#1365](https://github.com/ipfs-shipyard/ipfs-desktop/issues/1211). + +1. Download the `.dmg` from `https://github.com/ipfs-shipyard/ipfs-desktop/releases/vA.B.C`. +2. Ensure `APPLEID` and `APPLEIDPASS` are set either as environment variables or entries in `.env` file. These need to belong to the same org as the certificate used for signing. +3. Run `node pkgs/macos/notarize-cli.js ./IPFS-Desktop-A.B.C.dmg`. +4. Debug errors by calling the tool directly: `xcrun altool --notarize-app -f /path/to/IPFS-Desktop-0.X.0.dmg --primary-bundle-id io.ipfs.desktop -u XXX-from-vault-XXX -p XXX-app-specific-password-from-vault-XXX`; also, see the [long list of hoops Apple may ask you to jump through](https://github.com/ipfs-shipyard/ipfs-desktop/pull/1365#issuecomment-598127684). diff --git a/README.md b/README.md index dc6a9ef1e..d9d0ad37d 100644 --- a/README.md +++ b/README.md @@ -1,105 +1,124 @@ # IPFS Desktop -> A desktop client for [IPFS](https://ipfs.io). -> -> You don't need the command line to run an IPFS node. Just install IPFS Desktop and have all the power of IPFS in your hands. Powered by [Web UI](https://github.com/ipfs-shipyard/ipfs-webui). - -**Download the latest release** - -- Mac - [IPFS-Desktop-0.13.2.dmg](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-0.13.2.dmg) or `brew cask install ipfs` -- Windows - [IPFS-Desktop-Setup-0.13.2.exe](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-Setup-0.13.2.exe) or `choco install ipfs-desktop` -- Linux - see the [install](#install) section for available options - -![IPFS Desktop](https://gateway.ipfs.io/ipfs/QmbT2YtuNo17Qaq31FJWRZgRMY4E6N9cdfBwzZTFSHUoBP) - [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai/) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs) [![](https://david-dm.org/ipfs-shipyard/ipfs-desktop.svg?style=flat-square)](https://david-dm.org/ipfs-shipyard/ipfs-desktop) -[![total download count](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/total.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases) -[![latest release download count](https://img.shields.io/github/downloads-pre/ipfs-shipyard/ipfs-desktop/v0.13.2/total.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/tag/v0.13.2) +[![total download count](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/total.svg?style=flat-square&label=all%20downloads)](https://github.com/ipfs-shipyard/ipfs-desktop/releases) +[![latest release download count](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/v0.13.2/total.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/tag/v0.13.2) + +**IPFS Desktop gives you all the power of [IPFS](https://ipfs.io) in a convenient desktop app: a complete IPFS node, plus handy OS menubar/taskbar shortcuts and an all-in-one file manager, peer map, and content explorer.** + +Use IPFS Desktop to get acquainted with IPFS without needing to touch the terminal — or, if you're already experienced, use the powerful menubar/taskbar shortcuts alongside the command line to make your IPFS workflow faster. + +![Status screen of IPFS Desktop](https://gateway.ipfs.io/ipfs/QmYHuXitXMf5xTjiQXmXdqszvMTADvrM5zA7EqoDj3d3RH) + +| Files screen | Explore screen | Peers screen | Settings screen | Menubar/taskbar | +|-------|---------|-------|----------|------| +| ![Screenshot of the Files screen](https://gateway.ipfs.io/ipfs/QmRN82RPWHKuSuBadijTQuaCjFKAGaymt3aFBoG6Du9Vi3) | ![Screenshot of the Explore screen](https://gateway.ipfs.io/ipfs/Qmaerxh9UKf9F3YPKnV2cBEnPQoJdVmkswFdz7kNQGncKt) | ![Screenshot of the Peers screen](https://gateway.ipfs.io/ipfs/QmaVbBYsEBb34HMP1YWeErrS7X3TB6Y9t1iQ4sBRnTvSwa) | ![Screenshot of the Settings screen](https://gateway.ipfs.io/ipfs/Qmby5RuN7K9s5W9RVLdrQSE8gRKQ66EX8c39iC31DLAxN6) | ![Screenshot of Mac/Windows menus](https://gateway.ipfs.io/ipfs/QmbT2YtuNo17Qaq31FJWRZgRMY4E6N9cdfBwzZTFSHUoBP) | + +### Quick-install shortcuts -IPFS Desktop allows you to run your IPFS Node on your machine without having to bother with command line tools. With it, you have the power of [Web UI](https://github.com/ipfs-shipyard/ipfs-webui) on tip of your hands plus a handful of shortcuts you can find on settings. +- **Mac:** [IPFS-Desktop-0.13.2.dmg](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-0.13.2.dmg) or `brew cask install ipfs` +- **Windows:** [IPFS-Desktop-Setup-0.13.2.exe](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-Setup-0.13.2.exe) or `choco install ipfs-desktop` +- **Linux:** See [installation options](#install) below ## Table of Contents - [Features](#features) - [Install](#install) -- [Contribute](#contribute) - - [Translations](#translations) -- [FAQ](#faq) -- [Troubleshooting](#troubleshooting) +- [Contribute](#contribute) or [Translate](#translations) +- [FAQ & Troubleshooting](#faq--troubleshooting) ## Features -### IPFS daemon always running +IPFS Desktop combines a complete IPFS node (running [go-ipfs](https://github.com/ipfs/go-ipfs)) and the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui) into a single, convenient desktop app — plus adds a menu to your OS menubar/system tray for easy access to a variety of common IPFS tasks. -IPFS Desktop's main feature is to allow you to have the IPFS daemon always running in the background. But fear not! If you need to stop it, you can do it just by clicking on 'Stop'. +If you already have an IPFS node on your computer, IPFS Desktop will act as a control panel and file browser for that node. If you don't have a node, it'll install one for you. And either way, IPFS Desktop will automatically check for updates. -### Handle `ipfs://`, `ipns://` and `dweb:` links +### Start your node at system startup and control it from your OS -IPFS Desktop has the capacity to handle protocols at the operating system level; i.e., if an application tries to open a link to either `ipfs://`, `ipns://` or `dweb:`, then the OS will call IPFS Desktop, which will handle the link. +IPFS Desktop enables you to stop or restart your node straight from the IPFS logo menu in your OS menubar/system tray. For Mac and Windows users, IPFS Desktop can be also be set to launch at system startup, ensuring that your node is running whenever your computer is on. -For example, if you come across a link on the Internet whose `href` attribute is `ipns://ipfs.io`, then IPFS Desktop will be able to handle it. +### Quickly import files, folders, and screenshots to IPFS -On Windows, an easy way to open a link would be to open the Run window (Win+R), paste the link, and hit Enter. Then, IPFS Desktop handles the rest. The same happens if you try opening the same link in a browser. +Import files and folders to your IPFS node in a variety of convenient ways: +- Drag and drop items onto IPFS Desktop's `Files` screen +- Click the `Import` button on the `Files` screen to add items from your computer or an IPFS [content ID (CID)](https://docs.ipfs.io/concepts/content-addressing/#identifier-formats) +- (Windows) Right-click a file/folder's icon to add it to IPFS from the pop-up menu +- (Mac) Drag and drop a file/folder onto the IPFS logo in your menubar -### Adds `ipfs` to your system +Plus, you can use the `Take Screenshot` command under the IPFS logo menu to take a screenshot, import it to your node, and copy a shareable link to your clipboard with one click. -If you're using macOS or Windows and don't have `ipfs` installed on your system, IPFS Desktop will automatically install it so it is available through the command line. If you're using Linux, or already have `ipfs` installed, you can tell IPFS Desktop to take care of it (and keep it up to date!) by toggling the option on Settings. +### Easily manage the contents of your node -### Easy add to IPFS +IPFS Desktop's `Files` screen gives you an easy, familiar interface for working with the contents of your node: +- Easily rename, move, or remove files and folders +- Preview many common file formats directly in IPFS Desktop +- Copy a file/folder's IPFS [content ID (CID)](https://docs.ipfs.io/concepts/content-addressing/#identifier-formats) or a shareable link to your clipboard +- ["Pin"](https://docs.ipfs.io/concepts/persistence/) files to your IPFS node or (coming soon!) to a third-party pinning service -You can easily add files and folders to IPFS: +### Quick download for CIDs, IPFS paths, and IPNS paths -- On Windows, you can right click on files to add them to IPFS through IPFS Desktop. -- On macOS, you can drag and drop them to the tray icon. +Just want to download an IPFS content ID or IPFS/IPNS content path? Choose `Download...` from the IPFS logo menu, paste it in, and you're good to go. -### Download copied hashes +### Visualize your IPFS peers worldwide -You can enable, on Settings, a shortcut to download an hash on the keyboard. +Visit the `Peers` screen to see what nodes you're connected to, where they are, the connections they're using, and more. -### Auto-add screenshots +### Explore the "Merkle Forest" of IPFS files -You can enable, on Settings, a shortcut to take screenshots and add them automatically to IPFS. +Use the `Explore` screen to explore some example datasets — or your own files — and see firsthand how items stored on IPFS are broken down into content-addressed pieces. -## Install +### Enjoy OS-wide support for IPFS files and links + +IPFS Desktop enables most operating systems (Mac, Windows and some Linux flavors) to support protocols including `ipfs://`, `ipns://` and `dweb:`. This means that if an app on your computer tries to open a link starting with one of those protocol identifiers (for example, if your web browser encounters a link to `ipns://en.wikipedia-on-ipfs.org`), it'll automatically open in IPFS Desktop. -Download the latest release of IPFS Desktop for your OS, below. +For an even better experience with `ipfs://`, `ipns://` and `dweb:` addresses, we also recommend installing [IPFS Companion](https://github.com/ipfs-shipyard/ipfs-companion) to add support in your favorite browser! -| Platform | Download link | Download count -|---------:|---------------|--------------- -| **Windows** | [IPFS-Desktop-Setup-0.13.2.exe](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-Setup-0.13.2.exe) | [![](https://img.shields.io/github/downloads-pre/ipfs-shipyard/ipfs-desktop/v0.13.2/IPFS-Desktop-Setup-0.13.2.exe.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-Setup-0.13.2.exe) -| **Mac** | [IPFS-Desktop-0.13.2.dmg](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-0.13.2.dmg) | [![](https://img.shields.io/github/downloads-pre/ipfs-shipyard/ipfs-desktop/v0.13.2/IPFS-Desktop-0.13.2.dmg.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-0.13.2.dmg) +### Learn IPFS commands as you go -We provide multiple _experimental_ installers for **Linux** and **FreeBSD**: +If you're interested in learning how to use IPFS from the command line, IPFS Desktop's CLI Tutor Mode can show you common IPFS commands as you go. Just check the `CLI Tutor Mode` box on the `Settings` screen to switch on this feature. -| Package | Download link | Download count -|---------:|---------------|--------------- -| tar | [ipfs-desktop-0.13.2-linux-x64.tar.xz](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x64.tar.xz) | [![](https://img.shields.io/github/downloads-pre/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-x64.tar.xz.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x64.tar.xz) -| deb | [ipfs-desktop-0.13.2-linux-amd64.deb](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-amd64.deb) | [![](https://img.shields.io/github/downloads-pre/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-amd64.deb.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-amd64.deb) -| rpm | [ipfs-desktop-0.13.2-linux-x86_64.rpm](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.rpm) | [![](https://img.shields.io/github/downloads-pre/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.rpm.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.rpm) -| AppImage | [ipfs-desktop-0.13.2-linux-x86_64.AppImage](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.AppImage) | [![](https://img.shields.io/github/downloads-pre/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.AppImage.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.AppImage) -| freebsd | [ipfs-desktop-0.13.2-linux-x64.freebsd](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x64.freebsd) | [![](https://img.shields.io/github/downloads-pre/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-x64.freebsd.svg?style=flat-square)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x64.freebsd) +## Install -Or you can use your favorite package manager and a third-party package maintained by the community: +Release notes and older versions of IPFS Desktop can be found on the [releases page](https://github.com/ipfs-shipyard/ipfs-desktop/releases). -- **Homebrew** - `brew cask install ipfs` -- **Chocolatey** - `choco install ipfs-desktop` -- **Scoop** - `scoop install ipfs-desktop` -- **Snap** - `snap install ipfs-desktop` -- **AUR** - [`ipfs-desktop` package](https://aur.archlinux.org/packages/ipfs-desktop/) maintained by [@alexhenrie](https://github.com/alexhenrie) +Don't see your favorite package manager? Visit our [package managers page](https://github.com/ipfs-shipyard/ipfs-desktop/issues/691) and help us add support for it! -> Using package managers? Please head to [our package managers page](https://github.com/ipfs-shipyard/ipfs-desktop/issues/691) and help us add support for yours! +### Mac +- **Installer:** [IPFS-Desktop-0.13.2.dmg](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-0.13.2.dmg)\ +[![](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/v0.13.2/IPFS-Desktop-0.13.2.dmg.svg?style=flat-square&label=downloads)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-0.13.2.dmg) +- **Homebrew** (community-maintained): `brew cask install ipfs` -You can find releases notes and older versions on the [releases](https://github.com/ipfs-shipyard/ipfs-desktop/releases) page. +### Windows +- **Installer:** [IPFS-Desktop-Setup-0.13.2.exe](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-Setup-0.13.2.exe)\ +[![](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/v0.13.2/IPFS-Desktop-Setup-0.13.2.exe.svg?style=flat-square&label=downloads)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/IPFS-Desktop-Setup-0.13.2.exe) +- **Chocolatey** (community-maintained): `choco install ipfs-desktop` +- **Scoop** (community-maintained): `scoop install ipfs-desktop` -### Install from Source +### Linux/FreeBSD +- **Tarball** (experimental): [ipfs-desktop-0.13.2-linux-x64.tar.xz](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x64.tar.xz)\ +[![](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-x64.tar.xz.svg?style=flat-square&label=downloads)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x64.tar.xz) +- **Debian** (experimental): [ipfs-desktop-0.13.2-linux-amd64.deb](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-amd64.deb)\ +[![](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-amd64.deb.svg?style=flat-square&label=downloads)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-amd64.deb) +- **Red Hat** (experimental): [ipfs-desktop-0.13.2-linux-x86_64.rpm](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.rpm)\ +[![](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.rpm.svg?style=flat-square&label=downloads)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.rpm) +- **AppImage** (experimental): [ipfs-desktop-0.13.2-linux-x86_64.AppImage](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.AppImage)\ +[![](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.AppImage.svg?style=flat-square&label=downloads)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x86_64.AppImage) +- **FreeBSD** (experimental): [ipfs-desktop-0.13.2-linux-x64.freebsd](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x64.freebsd)\ +[![](https://img.shields.io/github/downloads/ipfs-shipyard/ipfs-desktop/v0.13.2/ipfs-desktop-0.13.2-linux-x64.freebsd.svg?style=flat-square&label=downloads)](https://github.com/ipfs-shipyard/ipfs-desktop/releases/download/v0.13.2/ipfs-desktop-0.13.2-linux-x64.freebsd) +- **Snapcraft** (community-maintained): `snap install ipfs-desktop` +- **AUR** (maintained by [@alexhenrie](https://github.com/alexhenrie)): Use the [`ipfs-desktop` package](https://aur.archlinux.org/packages/ipfs-desktop/) -To install it from source you need [Node.js](https://nodejs.org/en/) `>=12` and -need [npm](npmjs.org) `>=6.1.0` installed. This uses [`node-gyp`](https://github.com/nodejs/node-gyp) so **you must take a look** at their [platform specific dependencies](https://github.com/nodejs/node-gyp#installation). +### Install from source -Then follow the steps below to clone the source code, install the dependencies and run it the app: +To install and run IPFS Desktop from source, you'll also need: +- [Node.js](https://nodejs.org/en/) `>=12` +- [npm](npmjs.org) `>=6.1.0` +- Any [platform-specific dependencies](https://github.com/nodejs/node-gyp#installation) required by [`node-gyp`](https://github.com/nodejs/node-gyp) + +Then, follow the steps below to clone the source code, install dependencies, and run the app. ```bash git clone https://github.com/ipfs-shipyard/ipfs-desktop.git @@ -109,116 +128,93 @@ npm run build npm start ``` -The IPFS Desktop app will launch and should appear in your OS menu bar. - -## Translations - -The translations are stored on [./assets/locales](./assets/locales) and the English version is the source of truth. -Other languages are periodically pulled from [Transifex](https://www.transifex.com/ipfs/ipfs-desktop/), a web interface to help us translate IPFS Desktop and its components to another languages. - -## Releasing - -- Manually test a few things that don't transfer well to automated testing: - - Mac/Win/Linux: confirm that "Take Screenshot" under menubar/system tray menu works as expected for both single- and multi-monitor setups (file(s) imported, correct link copied to clipboard) - - Mac only: drag/drop onto menubar icon behaves as expected when dragging one file, several files, and a combination of files/folders (file(s) imported, correct link copied to clipboard) - - Win only: right-click on a file and "Add to IPFS" from context menu works as expected (file imported, correct link copied to clipboard) - - Mac/Win: confirm that OS-wide protocol handler got registered by opening `ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi` in user agent without IPFS Companion -- Fetch new translations from Transifex: `tx pull -a` -- Commit the changes -- Bump the version in `package.json` -- Commit the changes -- Create a tag with the same version: `git tag vA.B.C` -- Publish local changes and the tag to GitHub repo: `git push && git push origin vA.B.C` -- Wait for the CI to upload the binaries to the draft release (a new one will be created if you haven't drafted one). -- Publish release draft. - - Once a release is published, users should receive the app update. See: https://www.electron.build/auto-update. - - The `latest.yml, latest-mac.yml, latest-linux.yml` files on the release are used by the app to determine when an app update is available. -- Update links and badges in `README.md` to point to the new version (`A.B.C`) -- Update `CHANGELOG.md` with details from release/release draft -- Update selected package managers - - Wait for CI to finish and confirm it updated [Snap](https://snapcraft.io/ipfs-desktop) and is at least pending review on [Chocolatey](https://chocolatey.org/packages/ipfs-desktop#versionhistory). - - Update [Homebrew Cask](https://github.com/Homebrew/homebrew-cask/blob/master/CONTRIBUTING.md#updating-a-cask). -- To start work on the next version, bump the version in the `package.json` - -### Manual notarization (Fallback in-case CI is not doing it correctly) - -- Notarize `.dmg` at Apple (context: [#1365](https://github.com/ipfs-shipyard/ipfs-desktop/issues/1211)) - 1. Download `.dmg` from `https://github.com/ipfs-shipyard/ipfs-desktop/releases/vA.B.C` - 2. Ensure `APPLEID` and `APPLEIDPASS` are set either as environment variables or entries in `.env` file. Those need to belong to the same org as cert used for signing. - 3. Run `node pkgs/macos/notarize-cli.js ./IPFS-Desktop-A.B.C.dmg` - 4. Debug errors by calling the tool directly: `xcrun altool --notarize-app -f /path/to/IPFS-Desktop-0.X.0.dmg --primary-bundle-id io.ipfs.desktop -u XXX-from-vault-XXX -p XXX-app-specific-password-from-vault-XXX`, also see the [long list of hoops Apple might ask you to jump through](https://github.com/ipfs-shipyard/ipfs-desktop/pull/1365#issuecomment-598127684). - ## Contribute -[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/#contributing-guidelines) - -Feel free to join in. All welcome. Open an [issue](https://github.com/ipfs-shipyard/ipfs-desktop/issues)! - -If you're interested in contributing translations, go to [project page on Transifex](https://www.transifex.com/ipfs/ipfs-desktop/), create an account, pick a language and start translating. - -This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). - -## FAQ +We welcome all contributions to IPFS Desktop! The best way to get started is to check the current [open issues](https://github.com/ipfs-shipyard/ipfs-desktop/issues) (or drill down specifically for [issues labeled "help wanted"](https://github.com/ipfs-shipyard/ipfs-desktop/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)) and find something interesting. All issues are categorized by the [standard label taxonomy](https://github.com/ipfs/community/blob/master/ISSUE_LABELS.md) used across the IPFS project, so you can also drill by topic (for example, [UX-related issues](https://github.com/ipfs-shipyard/ipfs-desktop/issues?q=is%3Aissue+is%3Aopen+label%3Atopic%2Fdesign-ux)). -### Where is the configuration and logs? +You may also enjoy taking part in the IPFS GUI & Web Browsers Working Group's biweekly meeting to catch up on the latest plans. This meeting does shift around, so please check the [IPFS Community Calendar](https://calendar.google.com/calendar/embed?src=ipfs.io_eal36ugu5e75s207gfjcu0ae84@group.calendar.google.com&ctz=UTC) for the latest day/time. -The configuration file and logs are located on: -- Mac: `~/Library/Application Support/IPFS Desktop/` -- Windows: `%appdata%/IPFS Desktop/` -- Linux: `~/.config/IPFS Desktop/` +No matter how you contribute, please be sure you read and follow the [IPFS Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) and the [IPFS Community Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). -For quick access to this folders, just right-click on your tray icon and then 'Logs Directory' or 'Configuration File', depending on what you want. +### Translations -### How do we select the IPFS repo location? +Contributing translations in your language is particularly valuable! We use Transifex to manage internationalization, which means you don't need to change a single line of code to add your translations — just sign up for a Transifex account. -We use [ipfsd-ctl](https://github.com/ipfs/js-ipfsd-ctl), which, in default conditions, will check `IPFS_PATH` environment variable. If not set, we fallback to `$HOME/.ipfs`. As soon as the first run has succeded, we save the information about the repository location in the configuration file, which becomes the source of truth. +Because IPFS Desktop app includes text from [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui) and [IPLD Explorer](https://github.com/ipfs-shipyard/ipld-explorer), you'll want to join all three Transifex projects in order to see all the text: +- https://www.transifex.com/ipfs/ipfs-desktop/ +- https://www.transifex.com/ipfs/ipfs-webui/ +- https://www.transifex.com/ipfs/ipld-explorer/ -### Which version of IPFS are we running? +*Note for developers: We use English as our source of truth. This means that if you add any new text, make those additions in [`./assets/locales/en.json`](./assets/locales/en.json) and they will automatically propagate in Transifex for other languages.* -Since we're using [ipfsd-ctl](https://github.com/ipfs/js-ipfsd-ctl), we have our own embedded IPFS binary. We try to always have the latest version. +### Developer notes -### Which flags do we use to boot IPFS? +For more detailed information about hacking on IPFS Desktop, including a release checklist, please see the full [developer notes](DEVELOPER-NOTES.md). -By default we use the flags `--migrate=true --routing=dhtclient ----enable-gc=true` when running the IPFS daemon. They can be changed via the configuration file, which can be easily accessed as mentioned above. +## FAQ & Troubleshooting -## Troubleshooting +### Why am I missing the system tray menu on Linux? -### No tray icon on Linux +IPFS Desktop is built using Electron, and unfortunately, poor system tray support has been a [longstanding problem with Electron apps](https://github.com/electron/electron/issues/21445). -Poor tray support is a long running problem with Electron apps: [electron/issues/21445](https://github.com/electron/electron/issues/21445). +You may wish to try troubleshooting according to the [Electron v9.3.0 docs](https://github.com/electron/electron/blob/v9.3.0/docs/api/tray.md#class-tray): -According to [electron/v9.3.0/docs/api/tray.md](https://github.com/electron/electron/blob/v9.3.0/docs/api/tray.md#class-tray): +- On Linux, the app indicator will be used if it is supported; otherwise `GtkStatusIcon` will be used +- On Linux distributions that only have app indicator support, you must install `libappindicator1` to make the tray icon work -* On Linux the app indicator will be used if it is supported, otherwise `GtkStatusIcon` will be used instead. -* On Linux distributions that only have app indicator support, you have to install `libappindicator1` to make the tray icon work. +If you've noticed that the old system tray is back in IPFS Desktop v0.13, this is because the Electron team [removed support for `StatusNotifier` and restored the old tray interface on Linux called `XEmbed`](https://github.com/electron/electron/issues/21445#issuecomment-634163402). -Why the old tray is back since v0.13? We had no control over this: Electron team [removed support for `StatusNotifier` and restored the old tray interface on Linux called `XEmbed`](https://github.com/electron/electron/issues/21445#issuecomment-634163402). +### Why can't I start IPFS Desktop under Debian 10? -### Does not start on Linux (Debian 10) - -Some Linux users may see an error like this: +Some Linux users may see one of the following errors when trying to launch IPFS Desktop: +When launching by double-clicking the app icon: > The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that chrome-sandbox is owned by root and has mode 4755. -or a very short one, when starting in a terminal: - +When launching from the terminal: ```console $ ipfs-desktop $Trace/breakpoint trap ``` -This is a known issue with Electron/Chrome and some hardened kernels. -If you are interested in details, read [this](https://github.com/ipfs-shipyard/ipfs-desktop/issues/1362#issuecomment-596857282). - -The only reliable way to fix this at the moment is to start the app with additional parameter: - +This is a known issue with Electron/Chrome and some hardened kernels. More details can be found [here](https://github.com/ipfs-shipyard/ipfs-desktop/issues/1362#issuecomment-596857282), but a fix is to start IPFS Desktop from the terminal with the following additional parameter: ```console $ ipfs-desktop --no-sandbox ``` +### Where are my IPFS configuration and log files? + +You can open these files from the IPFS logo menu by selecting `Open Logs Directory` or `Open Configuration File` from the `Advanced` submenu. Or, find them in your OS as follows: +- **Mac:** `~/Library/Application Support/IPFS Desktop/` +- **Windows:** `%appdata%/IPFS Desktop/` +- **Linux:** `~/.config/IPFS Desktop/` + +### How does IPFS Desktop select the IPFS repo location? + +IPFS Desktop uses [ipfsd-ctl](https://github.com/ipfs/js-ipfsd-ctl), which, by default, checks the `IPFS_PATH` environment variable. If that isn't set, it falls back to `$HOME/.ipfs`. As soon as the first run has succeded, repository location info is saved in the configuration file, which becomes the source of truth. + +To open your repo directory from the IPFS logo menu, select `Open Repository Directory` from the `Advanced` submenu. + +### Which version of IPFS does IPFS Desktop use? + +IPFS Desktop includes its own embedded binary (with version defined in `package.json`); this is the latest version of [go-ipfs](https://github.com/ipfs/go-ipfs) that has passed QA for IPFS Desktop use. + +You can check which version of IPFS you're running from the IPFS logo menu by looking in the `About` submenu. + +### Which flags does IPFS Desktop boot with? + +By default, IPFS Desktop starts the IPFS daemon with the flags `--migrate=true --routing=dhtclient ----enable-gc=true`. + +You can change this in the IPFS Desktop config file by selecting `Open Configuration File` from the `Advanced` submenu. + +### I need more help! + +If you need help with using IPFS Desktop, the quickest way to get answers is to post them in the [official IPFS forums](https://discuss.ipfs.io). + +If you think you've found a bug or other issue with IPFS Desktop itself, please [open an issue](https://github.com/ipfs-shipyard/ipfs-desktop/issues/new/choose). ## License -[MIT Protocol Labs, Inc.](./LICENSE) +[MIT — Protocol Labs, Inc.](./LICENSE)