The Ultimate RPi Installation Guide

TODO

• Read about overclocking settings and apply if necessary
• Some devices trigger an alternative browser to sign-in when it figures out it is a captive portal, it is useless for us, but bot sure if there is a way to redirect it back to the main browser (spotted on some Android devices, but not all)

Basic Setup

MINIBIAN installation

Setting up SD Card

• Download MINIBIAN image: http://minibianpi.wordpress.com/download/
• Put image on SD Card:
• Stick SD Card in (duh)

mac

• First open terminal
• Find the disk that you are going to write to

diskutil list

• Find the disk name that reads something like /dev/disk<number> that doesn't have a partition on it named something like Macintosh HD. For example /dev/disk2

'To make it easier, and to avoid wiping external drives, make sure you have nothing else plugged in aside from your SD Card'

• You need to unmount the SD Card before imaging (replace <number> with the disk number found in the first step)

sudo diskutil unmountDisk /dev/disk<number>

• Then to image the disk with your image put in the following command (replace the minibian.img with the full path to your downloaded image file, and the <number> with the disk number that you found in the 1st step)

sudo dd bs=4m if=minibian.img of=/dev/rdisk<number>

linux

sudo dd bs=4M if=minibian.img of=/dev/sdc status=progress

• Insert SD, Power the RPi, wait for crazy blinking to stop

Connecting to the Pi

To connect to the Pi, you will need to connect it to a network. It will not connect by automatically to any Wifi network by default. You will need to connect it to a router, or other network by ethernet first. You can alternatively connect it directly to your personal machine via an ethernet cable - steps to do that can be found here.

If connecting to a normal network :

• Figure out what's the RPi IP (adjust mask to reflect own network)

nmap -sP 192.168.1.1-255

mac : you will need to install nmap manually from here. Easiest installation method is with the OSX Binaries.

• ssh into RPi (default MINIBIAN passwd is raspberry)

ssh root@192.168.1.73

Expand filesystem (optional)

This is optional. Indeed, depending on the application, the little room left on the minibian image might be just enough to add a couple software and config files. However, it is necessary if the kernel needs to be updated, as the process needs a bit more space than what we have by default. Also, you can repeat the process again at later stage if you need more space than the suggested 2GB total size in the example below. Just make sure you do not exceed the size of your medium/sdcard.

• install parted utility

apt update
apt install parted

• check that, indeed, it's a bit tight in there. The following command will show that the main system partition (partition 2 formatted as ext4) is roughly 700-800MB:

parted /dev/mmcblk0 --script print

• run the same command with unit s, to get more precise information (sectors)

parted /dev/mmcblk0 --script unit s print

• Note down the Start value of the partition Number 2. Here is an example:

 Number  Start     End       Size      Type     File system  Flags
  1      16s       125055s   125040s   primary  fat16
  2      125056s   1626111s  1501056s  primary  ext4

The value to remember in this example would be 125056s.

• Delete partition 2, you will get an error and complaining about the need to reboot, IGNORE THIS

parted /dev/mmcblk0 --script rm 2

• Double check that partition 2 is gone:

parted /dev/mmcblk0 --script print

• Create a new partition that starts exactly at the point 125056s but goes until 2GB. Adjust the command with your own value. Ignore the warning for now.

parted /dev/mmcblk0 --script mkpart primary 125056s 2GiB

• Check that new partition has been created

parted /dev/mmcblk0 --script print

• Reboot to make the system aware of the changes

reboot

• ssh back in and finally resize the filesystem to benefit from the expanded partition

resize2fs /dev/mmcblk0p2

Base system

• flavouring

echo "BMO" > /etc/hostname
hostname -F /etc/hostname

• don't bloat the system

echo -e 'APT::Install-Recommends "0";\nAPT::Install-Suggests "0";' > /etc/apt/apt.conf.d/90norecommend

• update system

apt update
apt upgrade

• update to latest kernel

apt install rpi-update
rpi-update
reboot

• Support for several terminals (needed when sshing from X using non-xterm terminals like urxvt)

apt install ncurses-term

• what time is it

dpkg-reconfigure tzdata

Comfy environment (optional)

Now you can install all your comfy l33t command line tools and whatnot, fav editors, etc. This is just an example of what I (aymeric) always put on top of my pi, YMMV:

• comfy tools and stuff

ln -s /usr/bin/vim.tiny /usr/bin/vim
apt install tmux tcsh git
chsh -s /bin/tcsh root

• create /root/.tcshrc

if ($?prompt) then
      set prompt = "%N@%m:%~ %# "
      set promptchars = "%#"
      set filec
      set history = 1000
      set savehist = (1000 merge)
      set autolist = ambiguous
      set autoexpand
      set autorehash
      if ( $?tcsh ) then
              bindkey "^W" backward-delete-word
              bindkey -k up history-search-backward
              bindkey -k down history-search-forward
      endif
endif

• logout and log back in

THIS IS IT!

Well done, you now have a minimal RPi installation, the guideline stops here, anything past this point is just a matter of what the RPi will be used for.

Extras

All the following steps are optional and depend on the use of the RPi.

Web Server

• nginx, what else :)

apt-get install nginx

• Go to http://192.168.1.20 (replace with the correct IP of your RPi), you should see the default Debian/nginx landing page
• For serving static documents, the default config can be kept and files just need to be put in:

/var/www/html

TODO: fcgiwrap, proxies (for nodejs or else).

Access Point with Captive Portal

• Misc stuff to install

apt-get install dnsmasq wireless-tools hostapd

• Make your wifi key work (sorry you'll have to figure this one on your own, too many different devices, avoid mini dongles, they're usually shit with staging drivers only, "old" large USB wifi dongles (b/g not n) are usually the most reliable). However, here are some instructions for getting the built-in brcmfmac wifi chip found in the RPi3:

apt install firmware-brcm80211
rmmod brcmfmac
modprobe brcmfmac

• Give fixed IP to wlan0 interface, edit /etc/network/interfaces and add at the end:

auto wlan0
iface wlan0 inet static
  address 10.10.10.10
  netmask 255.255.255.0

• Replace /etc/dnsmasq.conf with:

interface=wlan0
dhcp-range=10.10.10.11,10.10.10.254,12h
address=/#/10.10.10.10
no-resolv

• edit the /etc/hostapd/hostapd.conf file (adjust depending on driver/hardware)

interface=wlan0
driver=nl80211
ssid=WiFeels
hw_mode=g
channel=6

TODO: Add a note on the hw_mode and channel options.

• make hostapd starts at boot

update-rc.d hostapd defaults

• Edit /etc/default/hostapd and add

DAEMON_CONF="/etc/hostapd/hostapd.conf"

• Reboot
• If you have followed the Web Server extra, you can join the "WiFeels" wifi network and point your browser to http://itdoesnot.matter/whatyoutype and you will see the Debian/nginx landing page.

TODO: Add more info/config for proper portal detection/redirection (mostly for mobile phones and Apple devices).

Align Partitions

Only do it for production RPi setups and when the final medium/sdcard is chosen because it is hardware dependent. Skipping this part won't affect anything. In fact, most (if not all) standard RPi installations do not have proper partition alignment and most people do not know about it or care. To know why you should care and how it will affect performances, read https://superuser.com/questions/225936/what-does-it-mean-to-align-partitions.

Note: this operation can be done at any stage. So it can be skipped for now and done later if needed.

The partition that matters the most is /dev/mmcblk0p2, the one that contains the whole OS. On the RPi, it is possible to check if this partition is aligned:

parted /dev/mmcblk0 align-check optimal 2

The result is likely to be negative:

 2 not aligned

To fix this, the easiest way is to move the partition just a tiny bit and let parted do the math for correct alignment. There is catch though, because the partition will be moved, the data needs to be moved as well, and therefore the operation cannot be done live on the RPi, it must be done from another machine with the sdcard attached (directly or with a USB reader).

• take the sdcard from the RPi (after turning it off....)
• put it in the sdcard slot or USB sdcard adapter of another machine where gparted (a GUI equivalent of parted). You can do that manually with parted, resize3fs, e2image, etc, but it's kind of a PITA to do it manually in this particular case.
• Select your sdcard on the top right menu. In the examples below I will assume the sdcard is sdc, make sure you point to the right block device it will likely be different on yours.
• Select the second partition (we only need to align this one) and right-click to select resize.
• Make it so that you shrink the total size of 2MiB and that you add 1MiB empty at the beginning and 1MiB at the end.
• Right-click apply on the operation list. There will be a bunch of scary warnings, ignore them (assuming you're really working on the sdcard and not your own disk!).
• Wait, when done, quit gparted and verify alignement:

parted /dev/sdc align-check optimal 2  # will return "2 aligned" :)

Pinning

Pinning is a Debian specific method to mix packages from different versions of Debian. While this is not officially supported by Debian (ie, if you encounter an error with a software/package running on a pinned system, your bug report will be closed), it may be useful from time to time to install packages from the testing version of Debian that usually significantly more recent than the ones in the stable version of Debian.

• Create the file /etc/apt/preferences with the following content:

Package: *
Pin: release a=stable
Pin-Priority: 900

Package: *
Pin: release a=testing
Pin-Priority: 800

• Update the local package cache:

apt update

• To install whateversoftware from Debian stable, proceed as usual (same behaviour as before pinning):

apt install whateversoftware

• To install a more recent whateversoftware from Debian testing:

apt install whateversoftware -t testing

Read-only system

TODO

Making and Sharing images

TODO