## 1. Project Overview & Quickstart (balena-io/etcher) ## File: README.md # Etcher > Flash OS images to SD cards & USB drives, safely and easily. Etcher is a powerful OS image flasher built with web technologies to ensure flashing an SDCard or USB drive is a pleasant and safe experience. It protects you from accidentally writing to your hard-drives, ensures every byte of data was written correctly, and much more. It can also directly flash Raspberry Pi devices that support [USB device boot mode](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-device-boot-mode). [](https://balena.io/etcher) [](https://github.com/balena-io/etcher/blob/master/LICENSE) [](https://forums.balena.io/c/etcher) --- [**Download**][etcher] | [**Support**][support] | [**Documentation**][user-documentation] | [**Contributing**][contributing] | [**Roadmap**][milestones] ## Supported Operating Systems - Linux; most distros; Intel 64-bit. - Windows 10 and later; Intel 64-bit. - macOS 10.13 (High Sierra) and later; both Intel and Apple Silicon. ## Installers Refer to the [downloads page][etcher] for the latest pre-made installers for all supported operating systems. ## Packages #### Debian and Ubuntu based Package Repository (GNU/Linux x86/x64) Package for Debian and Ubuntu can be downloaded from the [Github release page](https://github.com/balena-io/etcher/releases/) ##### Install .deb file using apt ```sh sudo apt install ./balena-etcher_******_amd64.deb ``` ##### Uninstall ```sh sudo apt remove balena-etcher ``` #### Redhat (RHEL) and Fedora-based Package Repository (GNU/Linux x86/x64) ##### Yum Package for Fedora-based and Redhat can be downloaded from the [Github release page](https://github.com/balena-io/etcher/releases/) 1. Install using yum ```sh sudo yum localinstall balena-etcher-***.x86_64.rpm ``` #### Arch/Manjaro Linux (GNU/Linux x64) Etcher is offered through the Arch User Repository and can be installed on both Manjaro and Arch systems. You can compile it from the source code in this repository using [`balena-etcher`](https://aur.archlinux.org/packages/balena-etcher/). The following example uses a common AUR helper to install the latest release: ```sh yay -S balena-etcher ``` ##### Uninstall ```sh yay -R balena-etcher ``` #### WinGet (Windows) This package is updated by [gh-action](https://github.com/vedantmgoyal2009/winget-releaser), and is kept up to date automatically. ```sh winget install balenaEtcher #or Balena.Etcher ``` ##### Uninstall ```sh winget uninstall balenaEtcher ``` #### Chocolatey (Windows) This package is maintained by [@majkinetor](https://github.com/majkinetor), and is kept up to date automatically. ```sh choco install etcher ``` ##### Uninstall ```sh choco uninstall etcher ``` ## Support If you're having any problem, please [raise an issue][newissue] on GitHub, and the balena.io team will be happy to help. ## License Etcher is free software and may be redistributed under the terms specified in the [license]. [etcher]: https://balena.io/etcher [electron]: https://electronjs.org/ [electron-supported-platforms]: https://electronjs.org/docs/tutorial/support#supported-platforms [support]: https://github.com/balena-io/etcher/blob/master/docs/SUPPORT.md [contributing]: https://github.com/balena-io/etcher/blob/master/docs/CONTRIBUTING.md [user-documentation]: https://github.com/balena-io/etcher/blob/master/docs/USER-DOCUMENTATION.md [milestones]: https://github.com/balena-io/etcher/milestones [newissue]: https://github.com/balena-io/etcher/issues/new [license]: https://github.com/balena-io/etcher/blob/master/LICENSE --- ## File: docs/ARCHITECTURE.md Etcher Architecture =================== This document aims to serve as a high-level overview of how Etcher works, specially oriented for contributors who want to understand the big picture. Technologies ------------ This is a non exhaustive list of the major frameworks, libraries, and other technologies used in Etcher that you should become familiar with: - [Electron][electron] - [NodeJS][nodejs] - [Redux][redux] - [ImmutableJS][immutablejs] - [Sass][sass] - [Mocha][mocha] - [JSDoc][jsdoc] Module architecture ------------------- Instead of embedding all the functionality required to create a full-featured image writer as a monolithic project, we try to hard to follow the ["lego block approach"][lego-blocks]. This has the advantage of allowing other applications to re-use logic we implemented for Etcher in their own project, even for things we didn't expect, which leads to users benefitting from what we've built, and we benefitting from user's bug reports, suggestions, etc, as an indirect way to make Etcher better. The fact that low-level details are scattered around many different modules can make it challenging for a new contributor to wrap their heads around the project as a whole, and get a clear high level view of how things work or where to submit their work or bug reports. These are the main Etcher components, in a nutshell: - [Drivelist](https://github.com/balena-io-modules/drivelist) As the name implies, this module's duty is to detect the connected drives uniformly in all major operating systems, along with valuable metadata, like if a drive is removable or not, to prevent users from trying to write an image to a system drive. - [Etcher](https://github.com/balena-io/etcher) This is the *"main repository"*, from which you're reading this from, which is basically the front-end and glue for all previously listed projects. Summary ------- We always welcome contributions to Etcher as well as our documentation. If you want to give back, but feel that your knowledge on how Etcher works is not enough to tackle a bug report or feature request, use that as your advantage, since fresh eyes could help unveil things that we take for granted, but should be documented instead! [lego-blocks]: https://github.com/sindresorhus/ama/issues/10#issuecomment-117766328 [exit-codes]: https://github.com/balena-io/etcher/blob/master/lib/shared/exit-codes.js [gui-dir]: https://github.com/balena-io/etcher/tree/master/lib/gui [electron]: http://electron.atom.io [nodejs]: https://nodejs.org [redux]: http://redux.js.org [immutablejs]: http://facebook.github.io/immutable-js/ [sass]: http://sass-lang.com [mocha]: http://mochajs.org [jsdoc]: http://usejsdoc.org --- ## File: docs/COMMIT-GUIDELINES.md Commit Guidelines ================= We enforce certain rules on commits with the following goals in mind: - Be able to reliably auto-generate the `CHANGELOG.md` *without* any human intervention. - Be able to automatically and correctly increment the semver version number based on what was done since the last release. - Be able to get a quick overview of what happened to the project by glancing over the commit history. - Be able to automatically reference relevant changes from a dependency upgrade. Commit structure ---------------- Each commit message needs to specify the semver-type. Which can be `patch|minor|major`. See the [Semantic Versioning][semver] specification for a more detailed explanation of the meaning of these types. See balena commit guidelines for more info about the whole commit structure. ``` : ``` or ``` Change-Type: ``` The subject should not contain more than 70 characters, including the type and scope, and the body should be wrapped at 72 characters. Tags ---- ### `See: `/`Link: ` This tag can be used to reference a resource that is relevant to the commit, and can be repeated multiple times in the same commit. Resource examples include: - A link to pull requests. - A link to a GitHub issue. - A link to a website providing useful information. - A commit hash. Its recommended that you avoid relative URLs, and that you include the whole commit hash to avoid any potential ambiguity issues in the future. If the commit type equals `upgrade`, this tag should be present, and should link to the CHANGELOG section of the dependency describing the changes introduced from the previously used version. Examples: ``` See: https://github.com/xxx/yyy/ See: 49d89b4acebd80838303b011d30517cd6229fdbe Link: https://github.com/xxx/yyy/issues/zzz ``` ### `Closes: `/`Fixes: ` This tag is used to make GitHub close the referenced issue automatically when the commit is merged. Its recommended that you provide the absolute URL to the GitHub issue rather than simply writing the ID prefixed by a hash tag for convenience when browsing the commit history outside the GitHub web interface. A commit can include multiple instances of this tag. Examples: ``` Closes: https://github.com/balena-io/etcher/issues/XXX Fixes: https://github.com/balena-io/etcher/issues/XXX ``` [semver]: http://semver.org --- ## File: docs/CONTRIBUTING.md Contributing Guide ================== Thanks for your interest in contributing to this project! This document aims to serve as a friendly guide for making your first contribution. High-level Etcher overview -------------------------- Make sure you checkout our [ARCHITECTURE.md][ARCHITECTURE] guide, which aims to explain how all the pieces fit together. Developing ---------- ### Prerequisites #### Common - [NodeJS](https://nodejs.org) (at least v16.11) - [Python 3](https://www.python.org) - [jq](https://stedolan.github.io/jq/) - [curl](https://curl.haxx.se/) - [npm](https://www.npmjs.com/) ```sh pip install -r requirements.txt ``` You might need to run this with `sudo` or administrator permissions. #### Windows - [NSIS v2.51](http://nsis.sourceforge.net/Main_Page) (v3.x won't work) - Either one of the following: - [Visual C++ 2019 Build Tools](https://visualstudio.microsoft.com/vs/features/cplusplus/) containing standalone compilers, libraries and scripts - The [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools#windows-build-tools) should be installed along with NodeJS - [Visual Studio Community 2019](https://visualstudio.microsoft.com/vs/) (free) (other editions, like Professional and Enterprise, should work too) **NOTE:** Visual Studio doesn't install C++ by default. You have to rerun the setup, select "Modify" and then check `Visual C++ -> Common Tools for Visual C++` (see http://stackoverflow.com/a/31955339) - [MinGW](http://www.mingw.org) You might need to `npm config set msvs_version 2019` for node-gyp to correctly detect the version of Visual Studio you're using (in this example VS2019). The following MinGW packages are required: - `msys-make` - `msys-unzip` - `msys-zip` - `msys-bash` - `msys-coreutils` #### macOS - [Xcode](https://developer.apple.com/xcode/) It's not enough to have [Xcode Command Line Tools] installed. Xcode must be installed as well. #### Linux - `libudev-dev` for libusb (for example install with `sudo apt install libudev-dev`, or on fedora `systemd-devel` contains the required package) ### Cloning the project ```sh git clone --recursive https://github.com/balena-io/etcher cd etcher ``` ### Running the application #### GUI ```sh # Build and start application npm start ``` Testing ------- To run the test suite, run the following command: ```sh npm test ``` Given the nature of this application, not everything can be unit tested. For example: - The writing operating on real raw devices. - Platform inconsistencies. - Style changes. - Artwork. We encourage our contributors to test the application on as many operating systems as they can before sending a pull request. *The test suite is run automatically by CI servers when you send a pull request.* We make use of [EditorConfig] to communicate indentation, line endings and other text editing default. We encourage you to install the relevant plugin in your text editor of choice to avoid having to fix any issues during the review process. Updating a dependency --------------------- - Install new version of dependency using npm - Commit *both* `package.json` and `npm-shrinkwrap.json`. Diffing Binaries ---------------- Binary files are tagged as "binary" in the `.gitattributes` file, but also have a `diff=hex` tag, which allows you to see hexdump-style diffs for binaries, if you add the following to either your global or repository-local git config: ```sh $ git config diff.hex.textconv hexdump $ git config diff.hex.binary true ``` And global, respectively: ```sh $ git config --global diff.hex.textconv hexdump $ git config --global diff.hex.binary true ``` If you don't have `hexdump` available on your platform, you can try [hxd], which is also a bit faster. Commit Guidelines ----------------- See [COMMIT-GUIDELINES.md][COMMIT-GUIDELINES] for a thorough guide on how to write commit messages. Sending a pull request ---------------------- When sending a pull request, consider the following guidelines: - Write a concise commit message explaining your changes. - If applies, write more descriptive information in the commit body. - Mention the operating systems with the corresponding versions in which you tested your changes. - If your change affects the visuals of the application, consider attaching a screenshot. - Refer to the issue/s your pull request fixes, so they're closed automatically when your pull request is merged. - Write a descriptive pull request title. - Squash commits when possible, for example, when committing review changes. Before your pull request can be merged, the following conditions must hold: - The linter doesn't throw any warning. - All the tests pass. - The coding style aligns with the project's convention. - Your changes are confirmed to be working in recent versions of the operating systems we support. Don't hesitate to get in touch if you have any questions or need any help! [ARCHITECTURE]: https://github.com/balena-io/etcher/blob/master/docs/ARCHITECTURE.md [COMMIT-GUIDELINES]: https://github.com/balena-io/etcher/blob/master/docs/COMMIT-GUIDELINES.md [EditorConfig]: http://editorconfig.org [shrinkwrap]: https://docs.npmjs.com/cli/shrinkwrap [hxd]: https://github.com/jhermsmeier/hxd [Xcode Command Line Tools]: https://developer.apple.com/library/content/technotes/tn2339/_index.html --- ## File: docs/FAQ.md ## Why is my drive not bootable? Etcher copies images to drives byte by byte, without doing any transformation to the final device, which means images that require special treatment to be made bootable, like Windows images, will not work out of the box. In these cases, the general advice is to use software specific to those kind of images, usually available from the image publishers themselves. You can find more information [here](https://github.com/balena-io/etcher/blob/master/docs/USER-DOCUMENTATION.md#why-is-my-drive-not-bootable). ## How can I configure persistent storage? Some programs, usually oriented at making GNU/Linux live USB drives, include an option to set persistent storage. This is currently not supported by Etcher, so if you require this functionality, we advise to fallback to [UNetbootin](https://unetbootin.github.io/). ## How do I flash Ubuntu ISOs Ubuntu images (and potentially some other related GNU/Linux distributions) have a peculiar format that allows the image to boot without any further modification from both CDs and USB drives. A consequence of this enhancement is that some programs, like parted get confused about the drive's format and partition table, printing warnings such as: > /dev/xxx contains GPT signatures, indicating that it has a GPT table. However, it does not have a valid fake msdos partition table, as it should. Perhaps it was corrupted -- possibly by a program that doesn't understand GPT partition tables. Or perhaps you deleted the GPT table, and are now using an msdos partition table. Is this a GPT partition table? Both the primary and backup GPT tables are corrupt. Try making a fresh table, and using Parted's rescue feature to recover partitions. > Warning: The driver descriptor says the physical block size is 2048 bytes, but Linux says it is 512 bytes. All these warnings are safe to ignore, and your drive should be able to boot without any problems. Refer to [the following message from Ubuntu's mailing list](https://lists.ubuntu.com/archives/ubuntu-devel/2011-June/033495.html) if you want to learn more. ## How do I run Etcher on Wayland? The XWayland Server provides backwards compatibility to run any X client on Wayland, including Etcher. This usually works out of the box on mainstream GNU/Linux distributions that properly support Wayland. If it doesn't, make sure the xwayland.so module is being loaded by declaring it in your [weston.ini](http://manpages.ubuntu.com/manpages/wily/man5/weston.ini.5.html): ``` [core] modules=xwayland.so ``` ## What are the runtime GNU/LINUX dependencies? [This entry](https://github.com/balena-io/etcher/blob/master/docs/USER-DOCUMENTATION.md#runtime-gnulinux-dependencies) aims to provide an up to date list of runtime dependencies needed to run Etcher on a GNU/Linux system. ## How can I recover the broken drive? Sometimes, things might go wrong, and you end up with a half-flashed drive that is unusable by your operating systems, and common graphical tools might even refuse to get it back to a normal state. To solve these kinds of problems, we've collected [a list of fail-proof methods](https://github.com/balena-io/etcher/blob/master/docs/USER-DOCUMENTATION.md#recovering-broken-drives) to completely erase your drive in major operating systems. ## I receive "No polkit authentication agent found" error in GNU/Linux Etcher requires an available [polkit authentication agent](https://wiki.archlinux.org/index.php/Polkit#Authentication_agents) in your system in order to show a secure password prompt dialog to perform elevation. Make sure you have one installed for the desktop environment of your choice. ## May I run Etcher in older macOS versions? Etcher GUI is based on the [Electron](http://electron.atom.io/) framework, [which only supports macOS 10.10 and newer versions](https://github.com/electron/electron/blob/master/docs/tutorial/support.md#supported-platforms). ## Can I use the Flash With Etcher button on my site? You can use the Flash with Etcher button on your site or blog, if you have an OS that you want your users to be able to easily flash using Etcher, add the following code where you want to button to be: `[](https://efp.balena.io/open-image-url?imageUrl=)` --- ## File: docs/MAINTAINERS.md # Maintaining Etcher This document is meant to serve as a guide for maintainers to perform common tasks. ## Releasing ### Release Types - **draft**: A continues snapshot of current master, made by the CI services - **pre-release** (default): A continues snapshot of current master, made by the CI services - **release**: Full releases Draft release is created from each PR, tagged with the branch name. All merged PR will generate a new tag/version as a _pre-release_. Mark the pre-release as final when it is necessary, then distribute the packages in alternative channels as necessary. #### Preparation - [Prepare the new version](#preparing-a-new-version) - [Generate build artifacts](#generating-binaries) (binaries, archives, etc.) - [Draft a release on GitHub](https://github.com/balena-io/etcher/releases) - Upload build artifacts to GitHub release draft #### Testing - Test the prepared release and build artifacts properly on **all supported operating systems** to prevent regressions that went uncaught by the CI tests (see [MANUAL-TESTING.md](MANUAL-TESTING.md)) - If regressions or other issues arise, create issues on the repository for each one, and decide whether to fix them in this release (meaning repeating the process up until this point), or to follow up with a patch release #### Publishing - [Publish release draft on GitHub](https://github.com/balena-io/etcher/releases) - [Post release note to forums](https://forums.balena.io/c/etcher) - [Submit Windows binaries to Symantec for whitelisting](#submitting-binaries-to-symantec) - [Update the website](https://github.com/balena-io/etcher-homepage) - Wait 2-3 hours for analytics (Sentry) to trickle in and check for elevated error rates, or regressions - If regressions arise; pull the release, and release a patched version, else: - [Upload deb & rpm packages to Cloudfront](#uploading-packages-to-cloudfront) - Post changelog with `#release-notes` tag on internal chat - If this release packs noteworthy major changes: - Write a blog post about it, and / or - Write about it to the Etcher mailing list ### Generating binaries **Environment** Make sure to set the analytics tokens when generating production release binaries: ```bash export ANALYTICS_SENTRY_TOKEN="xxxxxx" ``` #### Linux ##### Clean dist folder Delete `.webpack` and `out/`. ##### Generating artifacts The artifacts are generated by the CI and published as draft-release or pre-release. Etcher is built with electron-forge. Run: ``` npm run make ``` Our CI will appropriately sign artifacts for macOS and some Windows targets. ### Uploading packages to Cloudfront Log in to cloudfront and upload the `rpm` and `deb` files. ### Dealing with a Problematic Release There can be times where a release is accidentally plagued with bugs. If you released a new version and notice the error rates are higher than normal, then revert the problematic release as soon as possible, until the bugs are fixed. You can revert a version by deleting its builds from the S3 bucket and Bintray. Refer to the `Makefile` for the up to date information about the S3 bucket where we push builds to, and get in touch with the balena.io operations team to get write access to it. The Etcher update notifier dialog and the website only show the a certain version if all the expected files have been uploaded to it, so deleting a single package or two is enough to bring down the whole version. Use the following command to delete files from S3: ```bash aws s3api delete-object --bucket --key ``` The Bintray dashboard provides an easy way to delete a version's files. ### Submitting binaries to Symantec - [Report a Suspected Erroneous Detection](https://submit.symantec.com/false_positive/standard/) - Fill out form: - **Select Submission Type:** "Provide a direct download URL" - **Name of the software being detected:** Etcher - **Name of detection given by Symantec product:** WS.Reputation.1 - **Contact name:** Balena.io Ltd - **E-mail address:** hello@etcher.io - **Are you the creator or distributor of the software in question?** Yes --- ## File: docs/MANUAL-TESTING.md # Manual Testing This document describes a high-level script of manual tests to check for. We should aim to replace items on this list with automated Spectron test cases. ## Image Selection - [ ] Cancel image selection dialog - [ ] Select an unbootable image (without a partition table), and expect a sensible warning - [ ] Attempt to select a ZIP archive with more than one image - [ ] Attempt to select a tar archive (with any compression method) - [ ] Change image selection - [ ] Select a Windows image, and expect a sensible warning ## Drive Selection - [ ] Open the drive selection modal - [ ] Switch drive selection - [ ] Insert a single drive, and expect auto-selection - [ ] Insert more than one drive, and don't expect auto-selection - [ ] Insert a locked SD Card and expect a warning - [ ] Insert a too small drive and expect a warning - [ ] Put an image into a drive and attempt to flash the image to the drive that contains it - [ ] Attempt to flash a compressed image (for which we can get the uncompressed size) into a drive that is big enough to hold the compressed image, but not big enough to hold the uncompressed version - [ ] Enable "Unsafe Mode" and attempt to select a system drive - [ ] Enable "Unsafe Mode", and if there is only one system drive (and no removable ones), don't expect autoselection ## Image Support Run the following tests with and without validation enabled: - [ ] Flash an uncompressed image - [ ] Flash a Bzip2 image - [ ] Flash a XZ image - [ ] Flash a ZIP image - [ ] Flash a GZ image - [ ] Flash a DMG image - [ ] Flash an image whose size is not a multiple of 512 bytes - [ ] Flash a compressed image whose size is not a multiple of 512 bytes - [ ] Flash an archive whose image size is not a multiple of 512 bytes - [ ] Flash an archive image containing a logo - [ ] Flash an archive image containing a blockmap file - [ ] Flash an archive image containing a manifest metadata file ## Flashing Process - [ ] Unplug the drive during flash or validation - [ ] Click "Flash", cancel elevation dialog, and click "Flash" again - [ ] Start flashing an image, try to close Etcher, cancel the application close warning dialog, and check that Etcher continues to flash the image ### Child Writer - [ ] Kill the child writer process (i.e. with `SIGINT` or `SIGKILL`), and check that the UI reacts appropriately - [ ] Close the application while flashing using the window manager close icon - [ ] Close the application while flashing using the OS keyboard shortcut - [ ] Close the application from the terminal using Ctrl-C while flashing - [ ] Force kill the application (using a process monitor tool, etc) In all these cases, the child writer process should not remain alive. Note that in some systems you need to open your process monitor tool of choice with extra permissions to see the elevated child writer process. ## GUI - [ ] Close application from the terminal using Ctrl-C while the application is idle - [ ] Click footer links that take you to an external website - [ ] Attempt to change image or drive selection while flashing - [ ] Go to the settings page while flashing and come back - [ ] Flash consecutive images without closing the application - [ ] Remove the selected drive right before clicking "Flash" - [ ] Minimize the application - [ ] Start the application given no internet connection ## Success Banner - [ ] Click an external link on the success banner (with and without internet connection) ## Elevation Prompt - [ ] Flash an image as `root`/administrator - [ ] Reject elevation prompt - [ ] Put incorrect elevation prompt password - [ ] Unplug the drive during elevation ## Unmounting - [ ] Disable unmounting and flash an image - [ ] Flash an image with a file system that is readable by the host OS, and check that is unmounted correctly --- ## File: docs/PUBLISHING.md Publishing Etcher ================= This is a small guide to package and publish Etcher to all supported operating systems. Release Types ------------- Etcher supports **pre-release** and **final** release types as does Github. Each is published to Github releases. The release version is generated automatically from the commit messasges. Signing ------- ### OS X 1. Get our Apple Developer ID certificate for signing applications distributed outside the Mac App Store from the balena.io Apple account. 2. Install the Developer ID certificate to your Mac's Keychain by double clicking on the certificate file. The application will be signed automatically using this certificate when packaging for OS X. ### Windows 1. Get access to our code signing certificate and decryption key as a balena.io employee by asking for it from the relevant people. 2. Place the certificate in the root of the Etcher repository naming it `certificate.p12`. Packaging --------- Run the following command on each platform: ```sh npm run make ``` This will produce all targets (eg. zip, dmg) specified in forge.config.ts for the host platform and architecture. The resulting artifacts can be found in `out/make`. Publishing to Cloudfront --------------------- We publish GNU/Linux Debian packages to [Cloudfront][cloudfront]. Log in to cloudfront and upload the `rpm` and `deb` files. Publishing to Homebrew Cask --------------------------- 1. Update [`Casks/etcher.rb`][etcher-cask-file] with the new version and `sha256` 2. Send a PR with the changes above to [`caskroom/homebrew-cask`][homebrew-cask] Announcing ---------- Post messages to the [Etcher forum][balena-forum-etcher] announcing the new version of Etcher, and including the relevant section of the Changelog. [aws-cli]: https://aws.amazon.com/cli [cloudfront]: https://cloudfront.com [etcher-cask-file]: https://github.com/caskroom/homebrew-cask/blob/master/Casks/balenaetcher.rb [homebrew-cask]: https://github.com/caskroom/homebrew-cask [balena-forum-etcher]: https://forums.balena.io/c/etcher [github-releases]: https://github.com/balena-io/etcher/releases Updating EFP / Success-Banner ----------------------------- Etcher Featured Project is automatically run based on an algorithm which promoted projects from the balena marketplace which have been contributed by the community, the algorithm prioritises projects which give uses the best experience. Editing both EFP and the Etcher Success-Banner can only be done by someone from balena, instruction are on the [Etcher-EFP repo (private)](https://github.com/balena-io/etcher-efp) --- ## File: docs/SUPPORT.md Getting help with BalenaEtcher =============================== There are various ways to get support for Etcher if you experience an issue or have an idea you'd like to share with us. Documentation ------ We have answers to a variety of frequently asked questions in the [user documentation][documentation] and also in the [FAQs][faq] on the Etcher website. Forums ------ We have a [Discourse forum][discourse] which is open to everyone, so please come join us :). Drop us a line there and the balena.io staff and community users will be happy to assist. Your question might already be answered, so take a look at the existing threads before opening a new one! Make sure to mention the following information to help us provide better support: - The BalenaEtcher version you're running. - The operating system you're running Etcher in. - Relevant logging output, if any, from DevTools, which you can open by pressing `Ctrl+Shift+I` or `Cmd+Alt+I` depending on your platform. GitHub ------ If you encounter an issue or have a suggestion, head on over to BalenaEtcher's [issue tracker][issues] and if there isn't a ticket covering it, [create one][new-issue]. [discourse]: https://forums.balena.io/c/etcher [issues]: https://github.com/balena-io/etcher/issues [new-issue]: https://github.com/balena-io/etcher/issues/new [documentation]: https://github.com/balena-io/etcher/blob/master/docs/USER-DOCUMENTATION.md [faq]: https://etcher.io --- ## File: docs/USER-DOCUMENTATION.md Etcher User Documentation ========================= This document contains how-tos and FAQs oriented to Etcher users. Config ------ Etcher's configuration is saved to the `config.json` file in the apps folder. Not all the options are surfaced to the UI. You may edit this file to tweak settings even before launching the app. Why is my drive not bootable? ----------------------------- Etcher copies images to drives byte by byte, without doing any transformation to the final device, which means images that require special treatment to be made bootable, like Windows images, will not work out of the box. In these cases, the general advice is to use software specific to those kind of images, usually available from the image publishers themselves. Images known to require special treatment: - Microsoft Windows (use [Windows USB/DVD Download Tool][windows-usb-tool], [Rufus][rufus], or [WoeUSB][woeusb]). - Windows 10 IoT (use the [Windows 10 IoT Core Dashboard][windows-iot-dashboard]) How can I configure persistent storage? --------------------------------------- Some programs, usually oriented at making GNU/Linux live USB drives, include an option to set persistent storage. This is currently not supported by Etcher, so if you require this functionality, we advise to fallback to [UNetbootin][unetbootin]. Deactivate desktop shortcut prompt on GNU/Linux ----------------------------------------------- This is a feature provided by [AppImages][appimage], where the applications prompts the user to automatically register a desktop shortcut to easily access the application. To deactivate this feature, `touch` any of the files listed below: - `$HOME/.local/share/appimagekit/no_desktopintegration` - `/usr/share/appimagekit/no_desktopintegration` - `/etc/appimagekit/no_desktopintegration` Alternatively, set the `SKIP` environment variable before executing the AppImage: ```sh SKIP=1 ./Etcher-linux-.AppImage ``` Flashing Ubuntu ISOs -------------------- Ubuntu images (and potentially some other related GNU/Linux distributions) have a peculiar format that allows the image to boot without any further modification from both CDs and USB drives. A consequence of this enhancement is that some programs, like `parted` get confused about the drive's format and partition table, printing warnings such as: > /dev/xxx contains GPT signatures, indicating that it has a GPT table. > However, it does not have a valid fake msdos partition table, as it should. > Perhaps it was corrupted -- possibly by a program that doesn't understand GPT > partition tables. Or perhaps you deleted the GPT table, and are now using an > msdos partition table. Is this a GPT partition table? Both the primary and > backup GPT tables are corrupt. Try making a fresh table, and using Parted's > rescue feature to recover partitions. *** > Warning: The driver descriptor says the physical block size is 2048 bytes, > but Linux says it is 512 bytes. All these warnings are **safe to ignore**, and your drive should be able to boot without any problems. Refer to [the following message from Ubuntu's mailing list](https://lists.ubuntu.com/archives/ubuntu-devel/2011-June/033495.html) if you want to learn more. Running on Wayland ------------------ Electron is based on Gtk2, which can't run natively on Wayland. Fortunately, the [XWayland Server][xwayland] provides backwards compatibility to run *any* X client on Wayland, including Etcher. This usually works out of the box on mainstream GNU/Linux distributions that properly support Wayland. If it doesn't, make sure the `xwayland.so` module is being loaded by declaring it in your [weston.ini]: ``` [core] modules=xwayland.so ``` Runtime GNU/Linux dependencies ------------------------------ This entry aims to provide an up to date list of runtime dependencies needed to run Etcher on a GNU/Linux system. ### Electron specific > See [brightray's gyp file](https://github.com/electron/brightray/blob/master/brightray.gyp#L4) - gtk+-2.0 - dbus-1 - x11 - xi - xcursor - xdamage - xrandr - xcomposite - xext - xfixes - xrender - xtst - xscrnsaver - gmodule-2.0 - nss ### Optional dependencies: - libnotify (for notifications) - libspeechd (for text-to-speech) ### Etcher specific: - liblzma (for xz decompression) Recovering broken drives ------------------------ Sometimes, things might go wrong, and you end up with a half-flashed drive that is unusable by your operating systems, and common graphical tools might even refuse to get it back to a normal state. To solve these kinds of problems, we've collected a list of fail-proof methods to completely erase your drive in major operating systems. ### Windows In Windows, we'll use [diskpart], a command line utility tool that comes pre-installed in all modern Windows versions. - Open `cmd.exe` from either the list of all installed applications, or from the "Run..." dialog usually accessible by pressing Ctrl+X. - Type `diskpart.exe` and press "Enter". You'll be asked to provide administrator permissions, and a new prompt window will appear. The following commands should be run **in the new window**. - Run `list disk` to list the available drives. Take note of the number id that identifies the drive you want to clean. - Run `select disk N`, where `N` corresponds to the id from the previous step. - Run `clean`. This command will completely clean your drive by erasing any existent filesystem. - Run `create partition primary`. This command will create a new partition. - Run `active`. This command will active the partition. - Run `list partition`. This command will show available partition. - Run `select partition N`, where `N` corresponds to the id of the newly available partition. - Run `format override quick`. This command will format the partition. You can choose a specific formatting by adding `FS=xx` where `xx` could be `NTFS or FAT or FAT32` after `format`. Example : `format FS=NTFS override quick` - Run `exit` to quit diskpart. ### OS X Run the following command in `Terminal.app`, replacing `N` by the corresponding disk number, which you can find by running `diskutil list`: ```sh diskutil eraseDisk FAT32 UNTITLED MBRFormat /dev/diskN ``` ### GNU/Linux Make sure the drive is unmounted (`umount /dev/xxx`), and run the following command as `root`, replacing `xxx` by your actual device path: ```sh dd if=/dev/zero of=/dev/xxx bs=512 count=1 conv=notrunc ``` "No polkit authentication agent found" error in GNU/Linux ---------------------------------------------------------- Etcher requires an available [polkit authentication agent](https://wiki.archlinux.org/index.php/Polkit#Authentication_agents) in your system in order to show a secure password prompt dialog to perform elevation. Make sure you have one installed for the desktop environment of your choice. Running in older macOS versions ------------------------------- Etcher GUI is based on the [Electron][electron] framework, [which only supports macOS 10.10 (Yosemite) and newer versions][electron-supported-platforms]. [balena.io]: https://balena.io [appimage]: http://appimage.org [xwayland]: https://wayland.freedesktop.org/xserver.html [weston.ini]: http://manpages.ubuntu.com/manpages/wily/man5/weston.ini.5.html [diskpart]: https://technet.microsoft.com/en-us/library/cc770877(v=ws.11).aspx [electron]: https://electronjs.org/ [electron-supported-platforms]: https://electronjs.org/docs/tutorial/support#supported-platforms [publishing]: https://github.com/balena-io/etcher/blob/master/docs/PUBLISHING.md [windows-usb-tool]: https://www.microsoft.com/en-us/download/windows-usb-dvd-download-tool [rufus]: https://rufus.akeo.ie [unetbootin]: https://unetbootin.github.io [windows-iot-dashboard]: https://developer.microsoft.com/en-us/windows/iot/downloads [woeusb]: https://github.com/slacka/WoeUSB See [PUBLISHING](/docs/PUBLISHING.md) for more details about release types. ## 2. Official Technical Reference & Guides (balena-io/docs) # balenaCloud Documentation Documentation for the [balenaCloud](https://balena.io/) platform lives here. Join our [forums](https://forums.balena.io/) to chat. This repo intends to provide our public-facing documentation. The documentation in this repo is hosted at https://docs.balena.io. ## How to Contribute If you think something is not documented, is outdated, or can be improved, don't hesitate to open a PR! Check our [CONTRIBUTING document](CONTRIBUTING.md) for the guidelines to ensure your PR can be merged as quickly as possible. One can open or check existing issues on [GitHub issues](https://github.com/balena-io/docs/issues). Looking forward to seeing your contributions! > Pro tip: Use the "Edit on GitHub" button to make changes to the correct file. It can be found via the dropdown by the `Ask` button ## Style manual ### Balena-specific words For all instances, we use `balena` as lower-case capitalization unless beginning a sentence (Ex. _I like balena. Balena is great._). More instances as follows, - **balena** (used to refer to the company as a whole, not in place of balenaCloud, balenaOS or any other project) - **balenaEtcher** - **balenaOS** (note the capitalization of **OS**) - **balenaEngine** - **balenaFin** - **balenaCloud** - the **balena CLI** - the **balena Supervisor** - **openbalena** ### Using Resuable Content When creating new content or altering current pages, it's recommended to try and keep things DRY (Don't Repeat Yourself). This is accomplished in the balenaCloud documentation by using "reusable content". The `/pages/.gitbook/includes` folder contain snippets of the docs, which can be reused anywhere in the documentation. To use reusable content in a page, all you need to do is add the following onto the page: ``` {% include "../../../.gitbook/includes/balena-example-projects.md" %} ``` > Warning: You are _not_ able to link to headings in reusable content. ## License The project is licensed under the Apache 2.0 license.