rewrite SETUP to cover box images

1 files changed, 111 insertions, 37 deletions

diff --git a/SETUP.md b/SETUP.md
index 6f695c1..8209bc9 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -2,66 +2,140 @@
 
 > Install Debian with Xfce from stable/testing image to encrypted disk
 
+This documents initial setting up a computer
+for use as desktop (or laptop) workstation.
 
-## Image
 
-Use Debian.
-Install either the [stable][] release for most reliable needs,
-or a [testing][] snapshot for more excitement.
+## Prerequisites
 
-You will need network access during install
-for downloading hundreds of megabytes of additional software from Debian.
+You need a locally usable computer
+(i.e. with monitor and keyboard connected).
+Requirements for computer:
 
-If your computer cannot use network with Free drivers
-(most wifi cards and a few wired cards),
-then you can try the [non-free stable] or [non-free testing] image.
-Use of those images is **not** recommended.
-Make sure that their **non-free** licensing terms are acceptable to you!
+* Sufficient: Any computer supported by [Debian].
+* Recommended: Either a [Teres-1] laptop or a [LIME2] box.
 
-[stable]: <https://www.debian.org/CD/netinst/>
-  "Official stable images, via Bittorrent or for direct download"
+You also need an install medium.
+For the recommended computers listed above,
+install medium is a microSD card.
+Requirements for microSD card:
 
-[testing]: <https://www.debian.org/devel/debian-installer/>
-  "Official testing images, via Bittorrent or for direct download"
+* Sufficient: Any microSD card that can hold at least 1GB storage.
+* Recommended: microSD card from SanDisk marked as "A1" or "A2".
+
+You will need internet access during install,
+both to get the install image
+and to finalize system setup.
+
+[Debian]: <https://www.debian.org/>
+  "Debian - the Universal Operating System"
+
+[Teres-1]: <https://www.olimex.com/Products/DIY-Laptop/>
+  "Olimex Teres-I Do-It-Yourself laptop"
+
+[LIME2]: <https://www.olimex.com/Products/OLinuXino/A20/A20-OLinuXino-LIME2/>
+  "Olimex A20-OLinuXino-LIME2"
+
+
+### Non-free firmware
 
-[non-free stable]: <https://cdimage.debian.org/images/unofficial/non-free/images-including-firmware/current/multi-arch/iso-cd/>
-  "Unofficial non-free stable images including firmware packages"
+**NB!**
+Many wifi controllers does not work out of the box
+with Free systems like [Debian].
+You can either avoid wifi (i.e. use ethernet instead),
+use a [Debian-compatible USB wifi dongle][Debian wifi],
+or (if acceptable to you) include suitable nonfree drivers.
 
-[non-free testing]: <https://cdimage.debian.org/images/unofficial/non-free/images-including-firmware/weekly-builds/multi-arch/iso-cd/>
-  "Unofficial non-free testing images including firmware packages"
+[Debian wifi]: <https://wiki.debian.org/WiFi#Availability_of_compatible_WiFi_chipsets>
+  "List of Debian-compatible wifi chipsets"
 
 
-## Disk protection
+## Install core system
 
-You are recommended to use full disk encryption.
+You are generally recommended to install a stable system.
+Alternatively you can install a testing system -
+more exciting but also less reliable.
 
-This protects your personal data stored on the harddisk
+You are recommended to use full disk encryption,
+which protects your personal data stored on the harddisk
 from being accessible by others
 e.g. if your computer gets stolen.
+Beware however that disk encryption only protects your data
+while the computer is **turned off**
+(also use a strong user password and a screensaver with locking).
+Also, if you forget your disk password then **all your data is lost!**
 
-Beware that disk encryption does not protect
-from access while the computer is turned on,
-and if you forget your disk password then the data is lost!
 
-During install,
-select "Guided - use entire disk and set up LVM"
-when formatting the harddisk.
+### Install box system
 
+For [recommended computers](#Prerequisites),
+follow the guide at <http://box.redpill.dk/>
+to download image and copy it over to an install medium,
+and then start the new system, enable network,
+and finalize system setup.
 
-## Desktop
+**NB!**
+Builtin wifi on the Teres-I laptop does not work
+with the regular box image
+(see notes [above][#Non-free firmware]).
+If including nonfree code is acceptable to you
+then you can instead use a [nonfree box image].
 
-The Xfce desktop is recommended
-as a conservative desktop environment.
+[nonfree box image]: <http://box.redpill.dk/images/nonfree/>
+  "Pre-installed 'box' images with nonfree firmware"
 
-You tell during installation that you want to [install Xfce].
 
-[install Xfce]: <https://wiki.debian.org/Xfce#How_to_install_Xfce>
-  "How to install Xfce"
+### Install Debian
+
+For non-recommended computers,
+download and install a suitable Debian netinst image -
+either [stable] release or a [testing] snapshot.
+
+(see notes [below][#Setup desktop on generic Debian])
+for setting up the Xfce desktop environment.
 
+You may find help
+in the [Install chapter of The Debian handbook][Debian handbook - Install].
 
-## See also
+**NB!**
+Builtin wifi on most computers does not work
+with regular netinst images
+(see notes [above][#Non-free firmware]).
+If including nonfree code is acceptable to you
+then you can instead use a [nonfree netinst image].
 
-Install chapter in The [Debian handbook][].
+[stable]: <https://www.debian.org/CD/netinst/>
+  "Official Debian stable images, via Bittorrent or for direct download"
+
+[testing]: <https://www.debian.org/devel/debian-installer/>
+  "Official Debian testing images, via Bittorrent or for direct download"
 
-[Debian handbook]: <https://www.debian.org/doc/manuals/debian-handbook/installation.html>
+[Debian handbook - Install]: <https://www.debian.org/doc/manuals/debian-handbook/installation.html>
   "Debian handbook, chapter on installation"
+
+[nonfree netinst image]: <https://cdimage.debian.org/images/unofficial/non-free/images-including-firmware/>
+  "Unofficial Debian-based netinst images with nonfree firmware"
+
+
+## Setup desktop
+
+You are recommended to use the Xfce desktop -
+as a conservative X11 desktop environment.
+
+
+## Setup desktop on boxed Debian
+
+Run "box-add-gui" to have a graphical user interface.
+
+
+## Setup desktop on generic Debian
+
+On non-box system
+(i.e. when installing with Debian netinst image)
+you tell during installation that you want to [install Xfce],
+or afterwards e.g. using this command:
+
+	sudo apt install task-xfce-desktop
+
+[install Xfce]: <https://wiki.debian.org/Xfce#How_to_install_Xfce>
+  "How to install Xfce"