Our installation instructions are optimizing for first time and less technical users, while still being usable by expert users.

The following scenarios are proposed:

• Install from Windows
• Install from macOS
• Install from Linux (all distributions)
• Install from Debian, Ubuntu, or Mint using the command line and GnuPG
• Clone from another Tails (for PC)
• Clone from another Tails (for Mac)
• Burn a DVD
• Run in a virtual machine
• Download only for USB sticks
• Download only for DVDs and virtual machines

The installation instructions are also adapted to cover 5 manual upgrade scenarios:

• Upgrade by cloning from another Tails
• Upgrade from Tails
• Upgrade from Windows
• Upgrade from macOS
• Upgrade from Linux

Related documents

• Design document of Tails Cloner
• Design document of the download verification
• Archive of our design artifacts
• Usability tests from December 2021

Implementation tricks

The installation instructions are presenting very similar content in many different scenarios with small variations: slightly different steps, slightly different terminology, etc.

To reuse as much content as possible and reduce the quantity of text and translations, our implementation relies heavily on 2 tricks. Both are quite hackish but were the only solution we found to avoid duplicating massive amount of content in ikiwiki.

Ikiwiki inlines

The inline directive of ikiwiki allows embedding a file into another file to avoid duplicating content. It is quite limited and brittle, especially when used together with the PO plugin. See #6907.

Conditional CSS content

To adapt a piece of content reused using ikiwiki inlines to the context where it appears we are using CSS classes. For example, to introduce the program used to install an intermediary Tails on Windows and Linux we wrote:

<span class="windows">a program called Etcher.</span>
<span class="linux">a program called GNOME Disks.</span>

Elements with the windows class being only displayed in the Windows scenario and elements with the linux class being only displayed in the Linux scenario.

• Classes for elements displayed only on one scenario:

  • windows for /install/windows
  • mac for /install/mac
  • linux for /install/linux
  • expert for /install/expert
  • dvd for /install/dvd
  • vm for /install/vm
  • download-only-img for /install/download
  • download-only-iso for /install/download
  • pc-clone for /install/clone
  • mac-clone for /install/mac/clone
  • upgrade-clone for /upgrade/clone
  • upgrade-tails for /upgrade/tails
  • upgrade-windows for /upgrade/win
  • upgrade-mac for /upgrade/mac
  • upgrade-linux for /upgrade/linux

• Classes for elements potentially displayed on different pages:

  • clone for content involving cloning:
    • pc-clone, upgrade-clone, mac-clone
  • usb for content with a USB stick as destination device (only for installation):
    • windows, mac, linux, expert
  • upgrade for content for manual upgrade:
    • upgrade-clone, upgrade-tails, upgrade-os
  • upgrade-os for content for manual upgrade from another OS
    • upgrade-windows, upgrade-mac, upgrade-linux

• Other classes:

  • standalone for content that should only be displayed outside of the installation instructions. For example on Starting Tails on PC.

Overview

The overview is the first part of an installation scenario and summarizes graphically:

• The requirements of the installation scenario in terms of hardware and time. This is important so that people get ready and make sure beforehand that they have everything needed to complete the scenario.
• The different steps. This give a rough idea of what will happen next and how complex it is, with links to each step to ease navigation.

Download

The download of the ISO image is the 1st step of the most common installation scenarios. It is also available as a standalone page.

We propose 2 download techniques displayed in equal weight:

a. Direct download.

b. BitTorrent download.

See our design document on download verification for a security analysis of the different verification techniques that we provide.

Steps

The detailed installation steps are given on the same page as the overview and download.

• Everything is on a single page so that people can get a feeling of what is left to be done and don't get lost between download and installation for example. During the tests, many people were scrolling up and down the page, for example while waiting for an operation to complete or when feeling that they missed something earlier.

• The content of each step is written in an inline stored in install/inc/steps/*.inline.mdwn which is inlined from the scenarios themselves (for example install/debian/usb.mdwn) and adapted to each scenario using CSS classes.

balenaEtcher

For Windows and macOS, we instruct people to use balenaEtcher to copy the USB image onto their USB stick. On top of this, we self-host the downloads of balenaEtcher on our own infrastructure. The https://gitlab.tails.boum.org/tails/etcher-binary repository is added as an ikiwiki underlay on our website.

We self-host a copy of balenaEtcher because:

• It gives us more predictability on what users end up doing. This is useful in terms of Help Desk.

• It prevents 3rd parties from learning a bit more about who uses Tails. Pointing to GitHub from our website would provide direct referrers to GitHub (and maybe Balena too) about who is using balenaEtcher to install Tails.

• It prevents GitHub from serving rogue downloads (targeted or not). We might still get a rogue download ourselves but:

  • We download balenaEtcher several times from different locations to prevent targeted attacks.

  • We download balenaEtcher in a limited time window, which might save our users some supply chain issues. If our users were to download balenaEtcher every time, a short-time supply chain attack would definitely affect some of them.