In 2015, we worked on a complete rewrite on our installation instructions. This work was extended in 2017 with the design of a new download page. The archive of our design process as well as pending issues can be found in the corresponding blueprint.

Our previous instructions forced people to jump through many different documentation pages and often to figure out by themselves what to do next. See this flowchart of the installation process as of 2014.

The objective was to make this a linear process, to be follow step-by-step, and that would take the user from our homepage up to starting on a Tails USB stick with a persistent volume. But this process has to be adapted to the base operating system of the user or their technical expertise.

We decided to optimize it for first time and less technical users, while still being usable by expert users.

The following scenarios are proposed:

The installation assistant is also adapted to cover two manual upgrade scenarios:

The assistant is divided into four sections:

  • The router which selects the scenario to follow.
  • The overview which summarizes graphically the scenario.
  • The download page for downloading and verifying the ISO image.
  • The steps which gives step-by-step instructions for the scenario after downloading.

Related documents

Implementation tricks

The installation assistant is basically 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 two 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. Many inlines also slow down the build process quite a lot.

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 Universal USB Installer.</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.


The router is a sequence of multiple choices that determines which installation scenario to follow. It is divided by operating systems:

  • Windows
  • macOS
  • Linux with APT and tails-installer: Debian, Ubuntu, or Mint
  • Other Linux distributions


  • Cloning is proposed as an alternative for all operating systems as it is easier and faster.

  • Download only is proposed as a minor option on the first page of the router. This is an example of us optimizing for first time users: installing Tails is very complex and we really want them to follow the full installation instructions and not only download and try to figure out the rest by themselves. This is especially true for those who think they are power users which is a good share of our audience.

    Download only is not offered as an option from the sidebar of the website for the same reason and to keep the sidebar as simple as possible.

  • Burning a DVD is also proposed as a minor option because:

    • DVD are not very popular (13% of the WhisperBack reports received in 2015).
    • DVD do not benefit from automatic upgrades, so people might be more quickly out-of-date.
    • DVD does not allow creating a persistent volume, so people cannot rely on long lasting cryptographic keys to secure their communication and might use weaker techniques.
    • For these same reasons we only provide a download and links to Ubuntu instructions in the scenario.
  • Running in a virtual machine is proposed as a minor option because:

    • VMs are not very popular (5% of the WhisperBack reports received in 2015).
    • VMs are less secure because the host operating system can monitor them.
    • VMs make it harder to create a persistent volume, so people might not rely on long lasting cryptographic keys to secure their communication and might use weaker techniques.
    • For these same reasons we only provide a download and then point to the documentation on virtualization.


The overview is a single page summarizing 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. This is particularly important as the steps are a single and very long page.

For example, the content of the overview for installing from Debian is stored in wiki/src/install/debian/usb-overview.html which includes a common block of HTML stored in wiki/src/install/inc/overview.html and uses the debian CSS class to adapt to the scenario.


The download of the ISO image comes as a dedicated page between the overview and steps (except for clone, upgrade-clone, and expert). It is also available as a standalone page.

The download is split as a dedicated page (while still labeled as "Step 1") to make it harder for people to skip the verification. It is still possible to skip the download or even the verification but the link to do so is labeled as a warning.

We propose two download techniques displayed in equal weight and combined with two verification techniques that have a level of verification at least as good as HTTPS:

  1. Direct download combined with a browser extension, called Tails Verification. See the dedicated design document for a security analysis of this technique.

  2. BitTorrent download. The Torrent file is downloaded through HTTPS from our website and BitTorrent clients automatically verifies the download once completed.

We advertise OpenPGP verification as an optional verification technique, possibly done on top of the other two techniques and ideally through the OpenPGP Web-of-Trust. We assume that this technique is only relevant for people who are already knowledgeable about OpenPGP. As a consequence:

  • We only provide simplified instructions on how to perform the verification, insisting on aspects that might still be relevant for this public: verification of the date, command line options, warning when the signing key is not trusted, etc.
  • We take more time to develop the verification of the signing key through the OpenPGP Web of Trust because it is the only technique that is really stronger than HTTPS.


The steps for a given scenario is a very long page with step-by-step instructions of the whole process.

  • It is a single page so that people can get a feeling of what is left to be done. 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.