Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/heeplr/rpi-cookstrap
bake customized raspberry pi sdcard images automatically
https://github.com/heeplr/rpi-cookstrap
bake bakery bash bootstrap bootstrapping deploy deploy-tool deployment deployment-automation disk-image provisioning raspberry raspberry-pi raspberrypi raspbian rpi rpi-cookstrap
Last synced: about 1 month ago
JSON representation
bake customized raspberry pi sdcard images automatically
- Host: GitHub
- URL: https://github.com/heeplr/rpi-cookstrap
- Owner: heeplr
- Created: 2021-04-18T21:47:16.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-09-02T16:29:39.000Z (over 1 year ago)
- Last Synced: 2024-04-26T16:31:51.406Z (8 months ago)
- Topics: bake, bakery, bash, bootstrap, bootstrapping, deploy, deploy-tool, deployment, deployment-automation, disk-image, provisioning, raspberry, raspberry-pi, raspberrypi, raspbian, rpi, rpi-cookstrap
- Language: Shell
- Homepage:
- Size: 357 KB
- Stars: 11
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## RPi CookStrap - [](https://github.com/heeplr/rpi-cookstrap/actions/workflows/blank.yml)
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](../../wiki/Doc-Plugins) + [bootstrap.cfg](../../wiki/Doc-Config) are building blocks to bake raspberry pi images
* **extendable** - plugins can use other [plugins](../../wiki/Doc-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](../../wiki/plugins).
Further documentation [can be found in the wiki](../../wiki/).
# Plugins
The wiki has a [list of available plugins](../../wiki/plugins).
There's also more [documentation on the general plugin concept](../../wiki/Doc-Plugins).
# More Examples
see [examples/](examples/) for "complete" examples and [plugin's](../../wiki/plugins) 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](https://github.com/heeplr/rpi-cookstrap/issues/new) 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](test/)
Contributions welcome!