raspbian-image-repository

Custom-built Raspberry Pi OS images

Table of contents

• Features
• Generate your custom images
• Configure your custom images
  • Target configuration properties
  • Example configuration
• Install your custom images to an SD card

Features

• Custom Raspberry Pi OS images
• Custom APT sources (with GPG key and key server support)
• Custom pre-installed packages (from APT repositories, GitHub releases, and direct URLs)
• Run custom commands before and/or after installing the packages
• Custom boot command line options
• Custom boot configuration options
• Run custom commands on first boot of the image
• Custom target build stage (default is 2 which results in the lite image)

Generate your custom images

1. Fork this repository

   

2. Clone your fork

   git clone https://github.com/<your-username>/raspbian-image-repository.git
   

3. Change config/target-config.json as per your requirements (See Configure your custom images section)

4. Commit and push the changes

5. Go to Actions tab in your forked repository and select Generate image workflow

   

6. Click on Run workflow button, set Image target name to the target name in config/target-config.json

   

7. Click on Run workflow button and wait for the workflow to complete

8. Go to the Releases page

   

9. Download the generated image

   

10. Install your custom images to an SD card (See Install your custom images to an SD card section)

Configure your custom images

The configuration file is located at config/target-config.json. It contains a list of target configurations.

Target configuration properties

Each configuration has the following properties:

• name: The name of the configuration to use as a reference
• version: The version of the configuration to distinguish between different versions of the same configuration
• reference: The reference (tag or commit hash) of the official Raspberry Pi OS pi-gen repository to be used as a base
• stage: The number of the target build stage to reach (optional, default is 2 which results in the lite image)
• sources: A list of custom APT sources to be added to the image (optional)
  • name: The name of the source to use as a reference
  • source: The source entry
  • key_id: The GPG key ID
  • key_file: The GPG key file URL (optional)
  • key_server: The GPG key server (optional)
• packages: A list of custom packages to be installed on the image
  • package: The name of the package
  • version: The version of the package (optional)
  • file_url: The URL of the package file (optional)
  • release: The release information of the package (optional)
    • owner: The owner of the repository
    • repo: The name of the repository
    • tag: The tag of the release
    • matcher: The matcher to filter the package file
    • token: The GitHub token to access a private repository, supports environment variable reference when $ is used like $GITHUB_TOKEN to avoid putting the access token directly in the configuration file (optional)
• boot_cmdline: A list of boot command line parameters to be added to the cmdline.txt file (optional)
• boot_config: A list of boot configuration parameters to be added to the config.txt file (optional)
• pre_install: A list of commands to be run before installing the packages (optional)
• post_install: A list of commands to be run after installing the packages (optional)
• first_boot: A list of commands to be run on the first boot of the image (optional)

Example configuration

A minimalist configuration to add an extra package to your image:

{
  "name": "bookworm-lite-with-dns-server",
  "version": "1.0.0",
  "reference": "2024-07-04-raspios-bookworm-arm64",
  "packages": [
    {
      "package": "dnsmasq"
    }
  ]
}

A more complex configuration to add custom packages, APT sources, and boot configuration:

{
  "name": "edge-pi-zero",
  "version": "1.0.0",
  "reference": "2024-03-12-raspios-bullseye",
  "sources": [
    {
      "name": "effective-range",
      "source": "deb http://aptrepo.effective-range.com stable main",
      "key_id": "C1AEE2EDBAEC37595801DDFAE15BC62117A4E0F3",
      "key_file": "http://aptrepo.effective-range.com/dists/stable/public.key",
      "key_server": "keyserver.ubuntu.com"
    }
  ],
  "packages": [
    {
      "package": "wifi-manager",
      "release": {
        "owner": "EffectiveRange",
        "repo": "wifi-manager",
        "tag": "latest",
        "matcher": "*armhf.deb"
      }
    },
    {
      "package": "picprogrammer",
      "release": {
        "owner": "EffectiveRange",
        "repo": "pic18-q20-programmer",
        "tag": "v0.3.0",
        "matcher": "*armhf.deb"
      }
    },
    {
      "package": "filebeat",
      "version": "8.12.2",
      "file_url": "https://github.com/EffectiveRange/elastic-beats-armhf-deb/releases/download/v8.12.2/filebeat-8.12.2-armv7l.deb"
    }
  ],
  "boot_cmdline": [
    "modules-load=dwc2,g_ether"
  ],
  "boot_config": [
    "enable_uart=1",
    "dtoverlay=dwc2"
  ],
  "first_boot": [
    "depmod",
    "reboot"
  ],
  "post_install": [
    "raspi-config nonint do_wifi_country HU",
    "raspi-config nonint do_i2c 0"
  ]
}

Install your custom images to an SD card

Flash the image to an SD card using Raspberry Pi Imager

1. Download and install the Raspberry Pi Imager

   

2. Open the Raspberry Pi Imager

   

3. Choose your Raspberry Pi Device type and Storage volume

4. Click Choose OS and select Use custom option

   

5. Select the custom image file you downloaded

   

6. Click NEXT and EDIT SETTINGS to configure the Wi-Fi, SSH and other settings

   

7. Click SAVE to apply the configuration

   

8. Click YES to flash the image to the SD card

   

9. After the flashing process is completed, insert the SD card into your Raspberry Pi and power it on