Quickstart Tutorial

Requires (1)
Ingo

This tutorial guides you on a basic setup of a debian based root filesystem. Without knowing anything about "wharfie", we can define what we want:

  • Bootable debian with systemd
  • Our desired username and password
  • Wireless network
  • SSH access

To make everything a bit more specific, we configure the system for the Raspberry Pi Zero W.

Step 1: Debian Base System

With the simple Statement "FROM", we can decide which debian version and which architecture we want to use. The exact syntax is:

FROM debian_<architecture>_<version>

When doing anything with the Raspberry Pi, you have to know which CPU version you have, as you will need to select the correct architecture. Don't think, that this is not necessary, as Raspbian can serve all variants with a single image. They can do this, as they selected a compromise between the two major architecture variants, which debian is using.

But no worries, the rule is easy:

  • Single Core: armel
  • Multi Core: armhf

As the Raspberry Pi Zero hosts a single core CPU, we are using "armel".

FROM debian_armel_stretch
TO rpi.tar

Step 2: Bootable debian with systemd

We are installing the following pakets:

  • systemd-sysv: This paket installs systemd, as well as the compatibility wrapper generator for system V. It is actually still a good idea, as some pakets (like dhcpcd5) still uses system V init scripts.
  • dhcpcd5: This will enable the configuration of the IP address, using DHCP.
  • wpa_supplicant: This will enable us to connect to a WPA secured access point.
  • openssh: This will enable SSH access to the device.

We will install everything with the following two flags:
-y to answer all questions during installation with "yes"
*-no-install-recommends to install only fix dependencies and keep the system small

RUN apt-get update && apt-get install -y -no-install-recommends systemd-sysv dhcpcd5 wpa_supplicant openssh

Now we just need the following actions, to add a proper /etc/fstab file.

ADD files/fstab /etc/fstab

Step 3: Username and password

It should be rather selfexplainatory. This concept is widely used in docker images to add specific users and change their passwords.

RUN useradd -ms /bin/bash wharfie; echo "wharfie:wharfie" | chpasswd; echo "root:root" | chpasswd;

Step 4: Wireless network

To load the network driver and to start wpa_supplicant for connecting to our access point, we use the following actions.

ADD files/wpa_supplicant.conf /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
ADD files/wireless.conf /etc/modules-load.d/wireless.conf
RUN sed -i 's,^Requires,#Requires,' /lib/systemd/system/wpa_supplicant@.service; \
    systemctl enable wpa_supplicant@wlan0.service;

We are starting wpa_supplicant for our interface wlan0. Dhcpcd is by default configured to assign IP addresses to every available network interface. So /etc/network/interfaces is not used at all.

Step 5: Make a bootable image

The result of the build would currently be a simple tar archive. To bring this root filesystem onto a bootable SD card image, containing a bootloader, a kernel, kernel modules and all necessary firmware files, we can use a script from the folder "examples/bootstrategy/raspberrypi.sh". This is downloading the most current raspian image and is exchanging the rootfilesystem.

RUN HOST \
    ../../bootstrategy/raspberrypi.sh rpi.img

Note, that RUN HOST is executed from a subfolder of your current working directory, which contains the full root filesystem. Therefore a relative path needs to contain an additional "../".

Final: The resulting file

All the steps above, need to be written into a file named "Wharfile". You should create a new folder for your image, where you can place this file.

The additional files which are needed can be placed where you like, but it's recommended to use a subfolder (e.g. "files/" or "root/") to collect all files which are added using the ADD command.

Here is the listing of the file. You file find a slighly changed version of it in the "examples" folder of wharfie.

FROM debian_armel_stretch
TO rpi.tar

RUN apt-get update && apt-get install -y -no-install-recommends systemd-sysv dhcpcd5 wpa_supplicant openssh

ADD files/fstab /etc/fstab

RUN useradd -ms /bin/bash wharfie; echo "wharfie:wharfie" | chpasswd; echo "root:root" | chpasswd;

ADD files/wpa_supplicant.conf /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
ADD files/wireless.conf /etc/modules-load.d/wireless.conf
RUN sed -i 's,^Requires,#Requires,' /lib/systemd/system/wpa_supplicant@.service; \
    systemctl enable wpa_supplicant@wlan0.service;

RUN HOST \
    ../../bootstrategy/raspberrypi.sh rpi.img

To build the image, just change into the newly created folder, containing the "Wharfile" and type the command "wharfie". You will be asked to enter your password, as some of the actions during build need root access.

After the image is created, it can be used on the target. In case of the Raspberry Pi from this example, the file "rpi.img" can be written on an SD card using the tool "dd".

Have fun!

Related

Home: IndexMain