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

The following scenarios are proposed:

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

Related documents

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.


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.


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.


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.


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.