Everything I do when setting up a new Raspberry Pi

I’m a big fan of Raspberry Pi. I have a few in my house doing various things, so from time to time I have to set up a new Pi, which involves a lot of steps.

There are heaps of how-to guides out there for setting up your Raspberry Pi, so this is mostly for my own reference!

1. Image the card with your OS

I use Raspberry Pi’s first-party Imager tool and install stock Raspbian, but there are lots of convenience images for different use cases (e.g. Homebridge).

2. Enable SSH and set up your network

  1. Create an empty file at the root of the newly-imaged boot volume: touch /Volumes/boot/ssh. This will start the sshd daemon when the system boots.

  2. If you’re connecting to WiFi, create a file at the root of the boot volume called wpa_supplicant.conf. At the top of the file, add:

     ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
 update_config=1
 country=<Insert 2 letter ISO 3166-1 country code here>
    Don’t forget to specify the country properly. Newer versions of Raspbian will ignore these network settings without it.

    Then, add each of the WiFi networks that you want configured:

     network={
     ssid="<network_name>"
     psk="<network_password"
 }

3. Set up user accounts

Eject your SD card, stick it in the Pi, and boot it up! It’ll connect to your network, and within a few moments you can connect over SSH using the default credentials: ssh pi@raspberrypi.local. The default password is raspberry.

If you aren’t able to SSH to your Pi at this point, your network might not allow local-area hostnames. Try using the Pi’s IP address instead. Also make sure your Pi is compatible with your network; as of writing, only Raspberry Pi 4 supports 5GHz WiFi networks.

  1. Change the password for the default pi account. Run passwd, then enter a new account password.

    Raspbian will most likely show you a warning message when you log in for the first time telling you that it’s a security risk to leave SSH enabled with the Pi user password unchanged.

  2. Create your user account: sudo useradd -m -G sudo <username>. I always add my user account to the sudo group; if you don’t want to, remove -G sudo.

  3. Set a password for your new user account: run sudo passwd <username> and enter a new account password.

  4. In a new Terminal window, try connecting with your new username and password: ssh <username>@raspberrypi.local. If everything works, great! You can close the other connection and continue working in your new user account.

4. Set up key-based SSH access

Key-based access is both convenient and far more secure than passwords. Once you set up key-based authentication, you’ll no longer be prompted for your user password when logging in to your Pi because you’ll supply a special private key file that proves your identity.

  1. Enable key-based authentication. Log in to your Pi using your password and edit the SSH configuration file: sudo nano /etc/ssh/sshd_config.

    Find the line that reads #PubkeyAuthentication yes. Remove the # to uncomment it and enable key-based authentication. Save and close the file, then restart the SSH daemon: sudo systemctl restart sshd.

  2. Generate a new key pair. On your computer (not your Pi), run ssh-keygen -t rsa -b 4096 -f <key_name>.pem.

    The key generator will ask if you want to set a passphrase. Doing so keeps your key safe even if someone else gets ahold of your private key, but is less convenient since you’ll once again be prompted for the passphrase to log in. I leave the passphrase blank so none is set.

    The key generator creates two files: <key_name>.pem and <key_name>.pem.pub. The former is your private key, the latter is the public key. You keep the private key safe, and store private key on your Pi. Together, they work like a lock and key, verifying your identity and allowing you to log in. The usual place to keep the private key is in ~/.ssh.

  3. Copy the public key to the Pi. Still on your computer, run ssh-copy-id -i ~/.ssh/<key_name>.pem.pub <username>@raspberrypi.local. You’ll be prompted for your Pi user password, and the key copy tool will move the public key into place on your Pi. Go ahead and try logging in using your private key: ssh -i ~/.ssh/<key_name>.pem. If everything worked right, you should be logged in!

  4. Disable password-based authentication. Now that you’ve upgraded to key-based authentication, disabling passwords makes logging in more secure.

    Once again, edit the SSH configuration file: sudo nano /etc/ssh/sshd_config. Find the line that reads #PasswordAuthentication yes. Uncomment the line, and change yes to no.

    While we’re editing the SSH configuration file, I like to increase the client keep-alive timeout so that SSH sessions don’t constantly disconnect. Find and update these lines:

     ClientAliveInterval 60
 ClientAliveCountMax 720

    Restart the SSH daemon again (sudo systemctl restart sshd), then logout of your Pi and try signing in with your private key again to make sure everything’s set up properly. At this point, you should be able to sign in with your private key, and not your password.

  5. (Optional) Change your Pi’s hostname to something more descriptive. On the Pi that runs Homebridge in my house, the hostname is homebridge, so I can address it at homebridge.local.

    Log in to your Pi and edit the file at /etc/hostname. This file contains only the plaintext hostname of the Pi. Change raspberrypi to whatever you want, in my example homebridge.

    Save and close /etc/hostname, then edit /etc/hosts. The very last line lists the localhost entry; replace raspberrypi with your new hostname, then save and close the file.

  6. (Optional) Add an SSH config entry for easier access. On your computer, edit ~/.ssh/config. Add a entry like this:

     Host raspberrypi
     HostName raspberrypi.local
     User <username>
     IdentityFile ~/.ssh/<private_key>.pem

5. Set up Git

Raspbian should include Git, but if your OS doesn’t, install it with apt install git-all.

I authenticate with GitHub using SSH keys in much the same way I log in to my Pi using keys:

  1. Once again, I’ll generate a new key pair, this time leaving the default id_rsa.pem destination: 

     ssh-keygen -t rsa -b 4096 -C "<your_github_email>"

  2. Copy the public key from id_rsa.pem.pub to the SSH keys section of your GitHub settings.

    Remember that when cloning repositories using SSH, the command looks slightly different: 

     git clone git@github.com:<owner>/<repo>.git

6. Install the essentials

Start by making sure all your pre-installed stuff is up-to-date: sudo apt upgrade -y.

I always like to have Python and Node installed and up-to-date:

curl -sL https://deb.nodesource.com/setup_12.x | sudo bash -
sudo apt-get install -y nodejs gcc g++ make python
If you’re setting up a Raspberry Pi Zero, the architecture is different, so use this to install node instead: 
sudo apt-get update
sudo apt-get install -y gcc g++ make python git
curl -Lf# "https://unofficial-builds.nodejs.org/download/release/v12.18.3/node-v12.18.3-linux-armv6l.tar.gz" | sudo tar xzf - -C /usr/local --strip-components=1 --no-same-owner

And perhaps Homebridge:

sudo npm install -g --unsafe-perm homebridge homebridge-config-ui-x