Raspberry Pi OS

Official Raspberry Pi OS Lite minimally modified with the ability to run a script on the first boot.

Supported script filenames:

• /boot/firstboot.sh - Just run the script on the first boot
• /boot/firstboot-script.sh - Same as above, except script is run with script(1) for complete session recording, that can be later played back using scriptreplay(1)

Repo is inspired by https://github.com/nmcclain/raspberian-firstboot, but has been automated, Dockerized, and fully scripted.

NOTE: If firstboot-script.sh is used, recording of script run is saved as /boot/firstboot-script-log.out (timing file alongside as firstboot-script-log.tm)

Usage

1. Download latest image

   <details><summary><b>Alternatives?</b></summary>

   If downloading images built by other people is not your thing, you can also:

   1. Modify images yourself using provided scripts (in Docker, or not), or even
   2. Manually apply all necessary modifications
   </details>

2. Burn it into a MicroSD Card

   <details><summary><b>How?</b></summary>
   1. Probably the easiest is to use Etcher
   2. Another way is using dd on Linux:

      dd bs=4M if=path/to/downloaded/file.img of=/dev/sdX conv=fsync
      

   3. Or MacOS:

      dd bs=4M if=path/to/downloaded/file.img of=/dev/diskX conv=fsync
      

   NOTE: boot partition will usually get mounted as /Volumes/boot/ on MacOS, and probably /mnt/boot/ on Linux.

   </details>

3. Mount it

   <details><summary><b>How?</b></summary>
   1. [MacOS] Simply re-inserting the card should do the trick, if not then diskutil, or Disk Utility should help
   2. [Linux] Hard to say exactly, but sth like:

   mkdir -p /mnt/boot/
   sudo mount /dev/sdX /mnt/boot/
   

   </details>

4. Add your script & mark it as executable

   # MacOS example:
   cd /Volumes/boot/
   
   cat <<EOF > firstboot-script.sh
   #!/bin/sh -e
   
   echo "Hello World!"
   EOF
   
   chmod +x firstboot-script.sh
   

5. Safely eject, move the card into Raspberry Pi, and power it on

Download

There are 4 possible ways, numbered from easiest to most manual.

1. Releases

The easiest way is going to Releases, and downloading the latest one.

Releases are created automatically upon each new Raspberry Pi OS release, you can see their build log either directly in Actions tab, or by searching for release-pending-approval issues.

2. Docker

Second easiest path is (after cloning this repo) running:

1. docker build -t builder .
2. docker run --rm --privileged -v="$(pwd)/images/:/raspios/" builder

NOTE: --privileged flag is required because mounting a filesystem requires root.

NOTE_2: Alternatively ./run-in-docker.sh can be run to achieve the same effect.

3. Script

If you're on a Linux box, you can (after cloning this repo) run:

./modify-image.sh create images/

NOTE: sudo might be required because mounting a filesystem requires root.

4. Manual

You can also completely ignore all contents of this repo, download Raspberry Pi OS Lite, and (assuming you have the ability to mount ext4 on your OS):

NOTE: For firstboot-script.service see here.

1. Mount second partition
2. Install the service, by creating $MOUNT_PATH/etc/systemd/system/firstboot.service file, with the following contents:

   [Unit]
   Description=FirstBoot
   After=network.target
   Before=rc-local.service
   ConditionFileNotEmpty=/boot/firstboot.sh
   
   [Service]
   Type=oneshot
   ExecStart=/boot/firstboot.sh
   ExecStartPost=/bin/mv /boot/firstboot.sh /boot/firstboot.sh.done
   RemainAfterExit=no
   
   [Install]
   WantedBy=multi-user.target
   

3. Enable the service by running:

   cd $MOUNT_PATH/etc/systemd/system/multi-user.target.wants/ && \
       ln -s /etc/systemd/system/firstboot.service . # No $MOUNT_PATH(!)
   

4. umount the image
5. Burn it to a card