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 artifacts from our design process are stored in Git.

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 the installation a linear process, to be followed step-by-step, and that would take the user from our homepage up to starting on a Tails USB stick with a Persistent Storage. 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 5 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 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.

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.


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

  • Windows
  • macOS
  • Linux


  • 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 Storage, 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 Storage, 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 Windows is stored in wiki/src/install/win/usb-overview.html which includes a common block of HTML stored in wiki/src/install/inc/overview.html and uses the windows 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 install-clone, mac-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.

Depending on the installation scenario, the download page points to the download of the ISO image (on dvd and vm) or the USB image (on all other scenarios).

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.


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.