installation_assistant.mdwn 10.5 KB
Newer Older
[[!meta title="Installation assistant"]]
sajolida's avatar
sajolida committed
2 3

In 2015, we worked on a complete rewrite on our installation
4 5
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
sajolida's avatar
sajolida committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
issues can be found in the [[corresponding

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

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:

sajolida's avatar
sajolida committed
24 25 26 27 28 29
  - [[Install from another Tails (for PC)|install/win/clone-overview]]
  - [[Install from another Tails (for Mac)|install/mac/clone-overview]]
  - [[Install from Windows|install/win/usb-overview]]
  - [[Install from Debian, Ubuntu, or Mint|install/debian/usb-overview]]
  - [[Install from Debian, Ubuntu, or Mint using the command line and GnuPG|install/expert/usb-overview]]
  - [[Install from other Linux distributions|install/linux/usb-overview]]
intrigeri's avatar
intrigeri committed
30 31
  - [[Install from macOS by burning a DVD first|install/mac/dvd-overview]]
  - [[Install from macOS and the command line|install/mac/usb-overview]]
sajolida's avatar
sajolida committed
  - [[Burn a DVD|install/dvd]]
33 34
  - [[Download only for USB sticks|install/download]]
  - [[Download only for DVDs and virtual machines|install/download-iso]]
sajolida's avatar
sajolida committed
35 36 37 38

The installation assistant is also adapted to cover two [[manual upgrade

sajolida's avatar
sajolida committed
39 40
  - [[Upgrade from another Tails|upgrade/clone-overview]]
  - [[Upgrade inside Tails|upgrade/tails-overview]]
sajolida's avatar
sajolida committed

The assistant is divided into four sections:
sajolida's avatar
sajolida committed

sajolida's avatar
sajolida committed
44 45
  - The [[*router*|installation_assistant#router]] which selects the scenario to follow.
  - The [[*overview*|installation_assistant#overview]] which summarizes graphically the scenario.
  - The [[*download*|installation_assistant#download]] page for downloading and verifying the ISO image.
sajolida's avatar
sajolida committed
  - The [[*steps*|installation_assistant#steps]] which gives step-by-step instructions for the scenario after downloading.
sajolida's avatar
sajolida committed

intrigeri's avatar
intrigeri committed
49 50
[[!toc levels=2]]

sajolida's avatar
sajolida committed
51 52 53
Related documents

- [[Design document of *Tails Installer*|verification_extension]]
sajolida's avatar
sajolida committed
- [[Design document of *Tails Verification*|verification_extension]]
sajolida's avatar
sajolida committed
- [[Blueprint with archives of the past design processes and notes on future work|blueprint/bootstrapping/assistant]]
sajolida's avatar
sajolida committed

sajolida's avatar
sajolida committed
Implementation tricks
sajolida's avatar
sajolida committed
sajolida's avatar
sajolida committed
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85

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 [[!tails_ticket 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

sajolida's avatar
sajolida committed
&lt;span class="windows"&gt;a program called Universal USB Installer.&lt;/span&gt;
sajolida's avatar
sajolida committed
87 88 89
&lt;span class="linux"&gt;a program called GNOME Disks.&lt;/span&gt;

90 91
Elements with the `windows` class being only displayed in the Windows
scenario and elements with the
sajolida's avatar
sajolida committed
92 93
`linux` class being only displayed in the Linux scenario.

- Classes for elements potentially displayed on different pages:
95 96 97
  - `clone` for content involving cloning
  - `usb` for content with a USB stick as destination device
  - `windows` for content for Windows
intrigeri's avatar
intrigeri committed
  - `mac` for content for macOS
99 100 101 102
  - `debian` for content for Debian, Ubuntu, or Mint
  - `expert` for content for Debian, Ubuntu, or Mint on the command line
  - `linux` for content for other Linux
  - `upgrade` for content for manual upgrade
- Classes for elements displayed only on one scenario:
104 105
  - `dvd` for [[/install/dvd-download|/install/dvd-download]]
  - `vm` for [[/doc/advanced_topics/virtualization|/doc/advanced_topics/virtualization]]
106 107
  - `download-only-img` for [[/install/download|/install/download]]
  - `download-only-iso` for [[/install/download|/install/download-iso]]
108 109 110 111 112 113 114 115 116 117 118
  - `install-clone` for [[/install/clone|/install/clone]]
  - `windows-usb` for [[/install/win/usb|/install/win/usb]]
  - `mac-usb` for [[/install/mac/usb|/install/mac/usb]]
  - `mac-dvd` for [[/install/mac/dvd|/install/mac/dvd]]
  - `mac-clone` for [[/install/mac/clone|/install/mac/clone]]
  - `debian-usb` for [[/install/debian/usb|/install/debian/usb]]
  - `expert-usb` for [[/install/expert/usb|/install/expert/usb]]
  - `linux-usb` for [[/install/linux/usb|/install/linux/usb]]
  - `upgrade-clone` for [[/upgrade/clone|/upgrade/clone]]
  - `upgrade-tails` for [[/upgrade/tails|/upgrade/tails]]

sajolida's avatar
sajolida committed
119 120 121
<a id="#router"></a>

sajolida's avatar
sajolida committed
sajolida's avatar
sajolida committed
123 124 125 126 127

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

  - Windows
intrigeri's avatar
intrigeri committed
  - macOS
sajolida's avatar
sajolida committed
129 130 131
  - Linux with `APT` and `tails-installer`: Debian, Ubuntu, or Mint
  - Other Linux distributions

132 133 134 135

- Cloning is proposed as an alternative for all operating systems as it is
  easier and faster.
sajolida's avatar
sajolida committed
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166

- *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
  - 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
  - VMs are less secure because the host operating system can monitor
  - 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.
167 168
  - For these same reasons we only provide a download and then point to the
    documentation on virtualization.
sajolida's avatar
sajolida committed
169 170 171 172

<a id="overview"></a>

sajolida's avatar
sajolida committed
sajolida's avatar
sajolida committed
174 175 176 177 178 179 180 181 182 183 184 185

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
  - 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
186 187
stored in [[!tails_gitweb wiki/src/install/debian/usb-overview.html]] which includes a common block of
HTML stored in [[!tails_gitweb wiki/src/install/inc/overview.html]] and uses the `debian` CSS
sajolida's avatar
sajolida committed
188 189 190 191
class to adapt to the scenario.

<a id="download"></a>

sajolida's avatar
sajolida committed
sajolida's avatar
sajolida committed

The download of the ISO image comes as a dedicated page between the
196 197
overview and steps (except for `clone`, `upgrade-clone`, and `expert`). It
is also available as a [[standalone page|install/download]].
sajolida's avatar
sajolida committed

199 200 201 202
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.
sajolida's avatar
sajolida committed

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

a. Direct download combined with a browser extension, called *Tails Verification*. See the [[dedicated design
   document|verification_extension]] for a security analysis of this technique.
sajolida's avatar
sajolida committed

b. BitTorrent download. The Torrent file is downloaded through HTTPS
   from our website and BitTorrent clients automatically verifies the download once
sajolida's avatar
sajolida committed
213 214

215 216 217 218 219 220 221 222 223 224
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
225 226
  through the OpenPGP Web of Trust because it is the only technique that is
  really stronger than HTTPS.
227 228 229 230

<a id="steps"></a>

sajolida's avatar
sajolida committed
232 233 234 235 236 237 238 239 240 241 242 243 244

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.