added README.md
This commit is contained in:
Benjamin Böhmke
127
README.md
Normal file
127
README.md
Normal file
@@ -0,0 +1,127 @@
|
|||||||
|
# Raspberry PI Alpine Linux Image Builder
|
||||||
|
|
||||||
|
Create minimal Linux images based on [Alpine Linux](https://alpinelinux.org/)
|
||||||
|
for the [Raspberry PI](https://www.raspberrypi.org/).
|
||||||
|
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
* Alpine base
|
||||||
|
* Small image size
|
||||||
|
* Fast image build
|
||||||
|
* A/B partition schema
|
||||||
|
* Simple update of whole system
|
||||||
|
* Fallback if update failed
|
||||||
|
* Single image for every Raspberry PI
|
||||||
|
* Read only root filesystem
|
||||||
|
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Image Creation
|
||||||
|
|
||||||
|
> A simple example for a go application can be found in the [example](example/)
|
||||||
|
> directory.
|
||||||
|
|
||||||
|
To generate an empty image simply run:
|
||||||
|
```
|
||||||
|
docker run --rm -it -v $PWD/output:/output bboehmke/raspi-alpine-builder
|
||||||
|
```
|
||||||
|
|
||||||
|
This will create 2 image files in the directory `$PWD/output/`:
|
||||||
|
* `alpine.img.gz`: complete SD card image for the raspberry
|
||||||
|
* `alpine_update.img.gz`: image of root partition to update running raspberry
|
||||||
|
|
||||||
|
> For each image a *.sha256 file will be generated to validate integrity.
|
||||||
|
|
||||||
|
To add custom modifications mount a script to `/input/image.sh`.
|
||||||
|
The following variables can be useful for the for and `image.sh`:
|
||||||
|
|
||||||
|
| Variable | Description |
|
||||||
|
| ----------- | --------------------------- |
|
||||||
|
| INPUT_PATH | Path to input directory |
|
||||||
|
| ROOTFS_PATH | Path to new root filesystem |
|
||||||
|
| BOOTFS_PATH | Path to new boot filesystem |
|
||||||
|
| DATAFS_PATH | Path to new data filesystem |
|
||||||
|
|
||||||
|
There is also a function `chroot_exec` that can be used to run command inside
|
||||||
|
the new root filesystem. To enable a service called `example_daemon` simple run:
|
||||||
|
```
|
||||||
|
chroot_exec rc-update add example_daemon default
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Config Variables
|
||||||
|
|
||||||
|
The following variables can be used to modify the base behaviour of the image
|
||||||
|
builder.
|
||||||
|
|
||||||
|
| Variable | Default Value | Description |
|
||||||
|
| --------------------- | ------------------------------------ | -------------------------------- |
|
||||||
|
| ALPINE_MIRROR | http://dl-cdn.alpinelinux.org/alpine | Mirror used for package download |
|
||||||
|
| ALPINE_BRANCH | 3.10 | [Alpine Branch](https://wiki.alpinelinux.org/wiki/Alpine_Linux:Releases) to use for image |
|
||||||
|
| DEFAULT_TIMEZONE | Etc/UTC | Default [Timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to use for image |
|
||||||
|
| DEFAULT_HOSTNAME | alpine | Default hostname |
|
||||||
|
| DEFAULT_ROOT_PASSWORD | alpine | Default password for root user |
|
||||||
|
| SIZE_BOOT | 100M | Size of boot partition |
|
||||||
|
| SIZE_ROOT_FS | 200M | Size of root file system |
|
||||||
|
| SIZE_ROOT_PART | 500M | Size of root partition |
|
||||||
|
| SIZE_DATA | 20M | Initial Size of data partition |
|
||||||
|
| IMG_NAME | sdcard | Base name of created image file |
|
||||||
|
|
||||||
|
### Update running system
|
||||||
|
|
||||||
|
The system can be updated without a complete flash of the SD card from the
|
||||||
|
running system with the following steps:
|
||||||
|
|
||||||
|
1. Transfer the update image to the running system
|
||||||
|
2. (Optional) Validate integrity of image with checksum file
|
||||||
|
3. Write the image to the actual inactive partition
|
||||||
|
4. Switch active partition
|
||||||
|
5. Reboot system
|
||||||
|
|
||||||
|
> An example implementation can be found in the helper script
|
||||||
|
> [ab_flash](resources/scripts/ab_flash)
|
||||||
|
|
||||||
|
## Image structure
|
||||||
|
|
||||||
|
### Partition Layout
|
||||||
|
|
||||||
|
The image contains 4 partitions:
|
||||||
|
|
||||||
|
1. **Boot:** (Size: `SIZE_BOOT`) \
|
||||||
|
Contains boot loader and boot configuration
|
||||||
|
|
||||||
|
2. **Root A:** (Size: `SIZE_ROOT_PART`) \
|
||||||
|
Contains complete root filesystem including all required kernels
|
||||||
|
|
||||||
|
3. **Root B:** (Size: `SIZE_ROOT_PART`) \
|
||||||
|
Same as *Root A*
|
||||||
|
|
||||||
|
4. **Data:** (Size: Initial `SIZE_DATA` & increases on first start) \
|
||||||
|
Contains persistent data for both root partitions
|
||||||
|
|
||||||
|
> With the exception of the data partition every partition is mounted read only
|
||||||
|
|
||||||
|
The A/B root partitions enables an easy and reliable way to update the complete
|
||||||
|
system. This is done by flashing the inactive partition with a new root
|
||||||
|
filesystem and make this partition active. If this new filesystem does not boot
|
||||||
|
the boot loader will fallback to the old partition.
|
||||||
|
|
||||||
|
The root file system should be as small as possible to reduce the update time
|
||||||
|
later. To support future increase of the root file system the partition should
|
||||||
|
contain some free space.
|
||||||
|
|
||||||
|
### Boot loader
|
||||||
|
|
||||||
|
To support the A/B partition schema the [U-Boot](https://www.denx.de/wiki/U-Boot)
|
||||||
|
boot loader is used.
|
||||||
|
|
||||||
|
The configuration/script for the boot loader can be found in the
|
||||||
|
[boot.cmd](resources/boot.cmd). This will boot the active root partition and
|
||||||
|
switch the active partition if the active one will not start.
|
||||||
|
> This script also select the right kernel for old Raspberry PIs
|
||||||
|
|
||||||
|
The image contains a simple tool that resets the boot counter and switch the
|
||||||
|
active partition from the running OS. The sources of the script can be found
|
||||||
|
in the [uboot.c](resources/uboot.c).
|
||||||
|
|
||||||
@@ -15,7 +15,7 @@ set -e
|
|||||||
: ${SIZE_ROOT_FS:="200M"}
|
: ${SIZE_ROOT_FS:="200M"}
|
||||||
: ${SIZE_ROOT_PART:="500M"}
|
: ${SIZE_ROOT_PART:="500M"}
|
||||||
: ${SIZE_DATA:="20M"}
|
: ${SIZE_DATA:="20M"}
|
||||||
: ${IMG_NAME:="alpine-${ALPINE_BRANCH}-sdcard"}
|
: ${IMG_NAME:="sdcard"}
|
||||||
|
|
||||||
|
|
||||||
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
|
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
|
||||||
|
|||||||
Reference in New Issue
Block a user