Update: There is now an official minimal Raspbian distribution available here. I have written an updated tutorial that is more focused on basic installation and configuration of Raspbian, and has additional information on security. This post is probably mostly irrelevant now, but I’m leaving it up because it may still contain some useful information.
Now that I’m done with college degree number three, I have time to pursue some project ideas that have been accumulating. The Raspberry Pi represents a pretty sweet platform for several of those projects. Raspbian is based on Debian Linux and is the standard operating system for the Raspberry Pi. The Raspberry Pi was initially developed as an educational tool, and as such, the Raspbian image and installer provided by the Raspberry Pi Foundation both result in a system with much more stuff (e.g. a full desktop environment) than I need or want for my embedded projects. The most recent official image, as of the time of writing, is a whopping 3.28 GiB.
In this tutorial I discuss using Raspbian (minimal) unattended netinstaller (raspbian-ua-netinst) to install a minimal Raspbian system on a headless Raspberry Pi. There are other ways to get a minimal system set up, including using the interactive installer available from Raspbian, or an image that someone else has made such as MINIBIAN. My reasons for doing it this way are:
Visit the raspbian-ua-netinst page on GitHub, read about the features and requirements, and download the latest release. In this tutorial I’m using 1.0.7. The README on GitHub has very good instructions for formatting your SD card and writing the image to it. On my Mac, I simply used the Disk Utility app included with OS X. After opening the app I selected the card, selected the Erase tab, selected MS-DOS (FAT) as the format, named the disk RASPBIAN, and clicked Erase. I then copied the contents of the .zip version of the release to the card using Finder. There are a lot of hidden files (dotfiles) in the archive, so make sure those get copied too.
In the root of the SD card, create a file named installer-config.txt. That file is where you can customize the installation. See README.md on GitHub for details. My few customizations are below, with comments. The next release (1.1.x) will offer more configuration options which will replace some of what I do later in the tutorial. If you are working with that release, take an extra thorough look at the documentation.
# This is default, but here as a reminder.
preset=server
# Hostname and root password
hostname=rubus
rootpw=raspbian
I have a background in biology. I tend to name my computers after famous biologists or using biological terminology. Rubus is the genus that contains raspberries, thus the hostname. As I get more Raspberry Pis, they will each get a species name as well (e.g. Rubus-strigosus, the American red raspberry).
Eject the card from your computer, stick it in the Raspberry Pi, connect the Pi via the Ethernet port to your internet connected network, and plug it in.
This installation will take some time. When the installation is complete, you will see the Pi on your home network and will be able to connect to it via SSH at its IP. The IP will likely be something other than the one below.
ssh root@192.168.2.2
There are some things that you will need to do by hand after installation completes. If you’re installing on many Pis, the steps below could be automated using a post-install.txt file. In that case though, it might make more sense to create a master image and clone it using dd or a similar utility.
There are sometimes issues with the locale settings on new Raspbian installs. Read here, here, here, and here. Considering all of that, this is what I did, but I’m not sure it’s the best way to solve the problem, so please do your own research. I live in the United States, so my locale is en_US.utf8; yours may be different.
locale-gen en_US.UTF-8
# The command below wouldn't run until I ran the previous command.
dpkg-reconfigure locales
# Once the menu was displayed, I selected "en_US.UTF-8 UTF-8" to be generated;
# on the next screen I selected "None" as the default locale.
dpkg-reconfigure tzdata
# Once the menu was displayed, I navigated to my time zone. Note that the
# United States has it's own category on the first screen.
# And now I reboot
shutdown -r now
apt-getapt-get update
apt-get upgrade
sudo, create a user, and disable rootThere are some strong opinions on how to best handle to root user on a UNIX system. I like to use sudo and disable the root user.
# install sudo
apt-get install sudo
# add a user
adduser pi
# make the user a sudoer
visudo
When your editor launches (probably Vim), under “User privilege specification”, copy the line beginning with “root”, replacing “root” with the name of the new user. In my case, the line was pi ALL=(ALL:ALL) ALL.
Logout with logout, then SSH back in with your new user. Now we will disable the root user.
# disable the root user
sudo passwd -l root
There are many editors available for Linux. I like Vim, but you may also want to consider Nano or Emacs.
The preset=server in installer-config.txt caused vim-tiny to be installed as /usr/bin/vim.tiny. I’m okay with that for now, but I want /usr/local/bin/vim symlinked to it so I can run it using the vim command.
sudo ln -s /usr/bin/vim.tiny /usr/local/bin/vim
While I’m at it, I’m going to set the default editor by adding the following to ~/.bashrc:
export VISUAL=vim
export EDITOR="$VISUAL"
/boot/config.txt contains settings for the Raspberry Pi hardware similar to what might be found in a typical computer’s BIOS settings. Check out the documentation here. I added the following to my file. Note that I have the camera module installed. Uncommenting disable_camera_led=1 will cause the LED on the camera not to illuminate when recording.
# Camera Module
startx=1
#disable_camera_led=1
# GPU Memory Allocation (min 128 for camera module)
gpu_mem=128
This may seem out of order, and it might be better done immediately after installation, but I wanted to wait until I had my editor set up. Plus it leads nicely into the next section on the camera module.
Now we reboot so the new settings become active.
sudo shutdown -r now
That completes the headless minimal base system with networking and access via SSH. Now, I’m going to install a few things that expand on that system. Here I install some tools that I use in my development environment.
sudo apt-get install git python3
I plan to use the camera module via the command line and Python 3. I was expecting to have to install the command line tools myself, but they were already installed in /opt/vc and symlinked in /usr/bin. How convenient! I did have to add my user pi to the video group by executing the following command:
usermod -a -G video pi
After logging out and back in. I took a quick test photo from the command line. I use the -vf and -hf arguments because my camera is upside down.
raspistill -vf -hf -o test.jpg
All that leaves is the library for Python 3.
sudo apt-get install python3-picamera
sudo apt-get install python3-rpi.gpio
avahi-daemonAfter all of that logging in an out, I’m sick of typing the Raspberry Pi’s IP address. Instead I want to access it using a hostname.local domain name like the rest of the computers on my network. What Apple calls Bonjour also goes by Rendesvous (the old Apple name for the technology), Zeroconf, mDNS/DNS-SD, and several other names.
Installation and setup are really simple on Raspbian.
sudo apt-get install avahi-daemon
Now I can log in via SSH with ssh pi@rubus.local. That was easy!
This recovers space by removing the package files downloaded during apt-get install commands. Those files are only needed for installation and can be safely deleted, which this command does.
sudo apt-get clean
We have installed and configured a headless minimal base Raspbian system on the Raspberry Pi complete with network access via SSH. We have also configured the camera module, and installed Python 3 and Git as a foundation for future development, along with Python 3 libraries to control GPIO and the camera module. Bonjour support was added as a convenience.
I hope that this tutorial can help smooth over some gaps in the existing documentation and help others configure a headless minimal Raspbian system to serve as a foundation for their projects.