RPi CookStrap -

A shell script to bake raspberry pi OS disk images

 

Features

• versatile - use plugins to download & mount image to copy/configure things to do on the first boot/login
• lightweight - written in bash, should run on any POSIX compatible system, no additional installation needed on the pi, configure with any text editor, will delete itself to leave no traces
• single shot - just generate the image on the host and everything else will happen automatically on the first boot (or first login if you choose so)
• dynamic - since the config is a bash script, you can create different images with the same configuration by setting config-values programmatically.
• customizable - do your personal customizations in ~ and use them with every project (e.g. your personal wifi credentials will override wifi credentials that are configured in a project)
• interoperable - uses shellscripts and standard tools
• reusable - plugins + bootstrap.cfg are building blocks to bake raspberry pi images
• extendable - plugins can use other plugins and can be written easily

 

Complete demo of image download, bootstrap, flash and setup on pi login.

(2x speed, most of it is output from apt on the pi, use pause if it's too fast)

 

Why?

If you work a lot with raspberry pi's, you find yourself repeatedly downloading OS images, customize settings like changing /config.txt, set the password, setup network, install packages, copy files etc.

With rpi-cookstrap you can create & use building blocks to build your final image by just running bootstrap.sh. When booting or logging in, the image can setup everything by itself non-interactively (default) or interactively.

 

Quickstart

$ RPI_BOOTSTRAP_PLUGINS=raspbian,password RPI_PASSWORD_PW=secret ./bootstrap.sh

is a minimal example and will download the latest raspbian lite and set the password of the pi user to "secret".

 

Basic usage by example

The wifi+upgrade example will create a working raspbian-lite image without any personal customizations. Wifi will be configured (with the preset SSID and PSK) and a full upgrade will be perfomed:

The following will:

• ...clone rpi-cookstrap
• ...load the project's bootstrap.cfg and download/modify the image accordingly.
• ...write the freshly baked image to your SD card (replace /dev/sdX with you sdcard)

$ git clone https://github.com/heeplr/rpi-cookstrap
$ cd rpi-cookstrap/examples/wifi+upgrade
$ ./bootstrap.sh
$ dd if=.bootstrap-work/raspbian-lite.img of=/dev/sdX conv=fsync status=progress

• Then boot raspberry pi with image
• login as "pi" like normal and wait until setup has finished (a line into /home/pi/.bashrc has been added. It executes the setup script which deletes itself after successful execution)

Now you got a fresh and fully upgraded image. But the wifi is setup with wrong credentials, since examples/wifi+upgrade/bootstrap.cfg doesn't contain your wifi's name and password (hopefully).

 

Integration into your project

You can add rpi-cookstrap into your raspberry project simply by using symbolic links. e.g. with a git submodule:

$ cd my-raspberry-project-image
$ git submodule add https://github.com/heeplr/rpi-cookstrap bootstrap
$ ln -s bootstrap/bootstrap.sh bootstrap.sh
$ ln -s bootstrap/bootstrap-plugins bootstrap-plugins

Then create bootstrap bootstrap.cfg and bootstrap-dist in your project directory (s. below).

 

Permanent customization

You can create a customized config that will always override a project's bootstrap.cfg: Create ~/.bootstrap.cfg and modify according to your needs, for example (comment out to disable):

# setup WIFI
RPI_BOOTSTRAP_PLUGINS+=( "wifi" )
RPI_WIFI_SSID="yourwifiname"
RPI_WIFI_PSK="your-secret-password"

# authorize SSH public key
RPI_BOOTSTRAP_PLUGINS+=( "ssh" )
RPI_SSH_AUTHORIZE=( "ssh-ed25519 AAAA... you@host" )

# set random 24 char PASSWORD for pi user
RPI_BOOTSTRAP_PLUGINS+=( "password" )
RPI_PASSWORD_PW=( "$(< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c24;echo;)" )

Now if you run ./bootstrap.sh for any project, the image is created with your personal settings.

 

Documentation

Try running ./bootstrap.sh -h to list commandline arguments and ./bootstrap.sh -p to list plugins.

Further documentation can be found in the wiki.

 

Plugins

The wiki has a list of available plugins. There's also more documentation on the general plugin concept.

 

More Examples

see examples/ for "complete" examples and plugin's documentation for plugin specific examples.

 

Troubleshooting

Everything should be straight forward & verbose. You can always rm -rf .bootstrap-work to clean up and start over. Feel free to file an issue or even submit a pull request.

 

ToDo

• lots of stuff still missing (plugins, plugin features)
• better documentation
• more examples
• dry-run mode (output all actions without performing them)
• more tests

Contributions welcome!