Pieman is a script for creating custom OS images for single-board computers such as Raspberry Pi. The images are based on Alpine and Debian-based distributions such as Devuan, Raspbian and Ubuntu. The authors of Pieman were inspired by the project named rpi23-gen-image. The main reason why it was decided to create a new project instead of improving the existing one is that rpi23-gen-image is intended for creating images only for Raspberry Pi 2 and 3 based on Debian GNU/Linux. Unfortunately, it doesn't have a way to be extended to support different operating systems and single-board computers. Improving the situation would require significant efforts to rework the codebase of the project.

• Getting Started
  • Dependencies
  • Supported platforms
  • Installation
    • Docker
    • Manual
• Documentation
  • Parameters
    • General
    • Networking
    • Package manager
    • Users
    • Image
    • Pieman-specific
• Daily image builds
• Authors
• Licensing
• Contribute

• dosfstools
• dpkg
• GNU Parted
• GnuPG
• mkpasswd
• Python (3.5 or higher)
• PyYAML
• rsync
• Setuptools
• uuidgen
• User mode emulation binaries such as /usr/bin/qemu-arm-static and /usr/bin/qemu-aarch64-static
• wget

• bzip2
• xz

Theoretically, Pieman can be run on any GNU/Linux, however, it was very carefully tested only on:

• Debian 9 «Stretch»
• Fedora 26
• Ubuntu 16.04 «Xenial Xerus»

First, get the latest Pieman Docker image from Docker Hub.

$ docker pull cusdeb/pieman

Then, get docker-pieman.sh

$ wget https://raw.githubusercontent.com/tolstoyevsky/pieman/master/docker-pieman.sh -O docker-pieman.sh

or using curl

$ curl -O https://raw.githubusercontent.com/tolstoyevsky/pieman/master/docker-pieman.sh

Note, that the script requires bash 4 or higher, so macOS users should upgrade their bash if they haven't done it yet.

Simply run docker-pieman.sh to create an image based on Raspbian Stretch for Raspberry Pi 3.

$ chmod +x docker-pieman.sh
$ ./docker-pieman.sh

Under the hood the script runs

$ docker run --privileged --rm -v $(pwd):/result -v /dev:/dev cusdeb/pieman

It's quite wordy, isn't it? docker-pieman.sh is intended to hide the details and provide an easy-to-use command-line interface.

Another example shows how to create an image based on Ubuntu Xenial for Raspberry Pi 2 with htop and mc pre-installed

$ ./docker-pieman.sh -e DEVICE=rpi-2-b -e OS=ubuntu-xenial-armhf -e INCLUDES=htop,mc

The built images will be located in the current directory. By the way, you can specify the name of your project via the PROJECT_NAME environment variable. You can find details on DEVICE, INCLUDES, OS, PROJECT_NAME and other environment variables (called parameters) which help customizing images in the Documentation section.

First, clone the Pieman git repo:

$ git clone https://github.com/tolstoyevsky/pieman.git

Then, install the Pieman dependencies.

On Debian or Ubuntu:

$ sudo apt-get install dosfstools gnupg parted python3-pip python3-setuptools python3-yaml qemu-user-static rsync uuid-runtime wget whois

On Fedora:

$ sudo dnf install dosfstools dpkg expect gpg parted python3-pip python3-PyYAML python3-setuptools qemu-user-static rsync wget

Finally, return to the project directory and run

$ sudo pip3 install pieman

to install the required utilities and modules written in Python.

Go to the project directory and execute the following command to create an image based on Raspbian Stretch for Raspberry Pi 3:

$ sudo ./pieman.sh

To create an image based on Ubuntu Xenial for Raspberry Pi 2 with htop and mc pre-installed run

$ sudo env DEVICE=rpi-2-b OS=ubuntu-xenial-armhf INCLUDES=htop,mc ./pieman.sh

The built image will be located in the build directory. By the way, you can specify the name of your project via the PROJECT_NAME environment variable. You can find details on DEVICE, INCLUDES, OS, PROJECT_NAME and other environment variables (called parameters) which help customizing images in the Documentation section.

The operating system of the target image is specified via the OS environment variable. The next table maps full names of the supported operating systems to their short name intended for using as values of OS.

The device the target image is created for is specified via the DEVICE environment variable. The next table maps full names of the supported devices to their short name intended for using as values of DEVICE.

Allows specifying the operating system to be used as a base for the target image. You can find all the possible values for the parameter in the table above (see the "Short name" column).

Allows specifying the device the image is going to be run on. You can find all the possible values for the parameter in the table above (see the "Short name" column).

Allows specifying the chroot environment to be used instead of creating a new one.

Note, that the parameter conflicts with CREATE_ONLY_CHROOT.

Each image is built in in the context of some project. The parameter allows specifying the project name. By default, the name is a randomly generated UUID 32-character string.

Allows specifying the projects location. By default, the directory named build is created in the current directory during the build process with ownership specified via IMAGE_OWNERSHIP.

Makes Pieman restrict itself to only creating a chroot environment based on the operating system specified via OS. The chroot environment is stored in build/${PROJECT_NAME}/chroot and can be used immediately or later to reduce the time of building images. See BASE_DIR.

Allows specifying the locale.

Allows specifying the directory into which Pieman is installed.

Makes Pieman restrict itself to only preparing or upgrading the toolset which is located in the directory specified via TOOLSET_DIR.

Specifies the time zone of the system.

Allows specifying the directory which contains the tools necessary for creating chroot environments based on Alpine Linux and different Debian-based distributions. The toolset consists of debootstrap and apk.static.

Enables the most common DNS server provided by Google.

The DNS IP addresses (IPv4) are the following:

• 8.8.8.8
• 8.8.4.4

Note, that the parameter conflicts with ENABLE_BASIC_YANDEX_DNS, ENABLE_FAMILY_YANDEX_DNS and ENABLE_CUSTOM_DNS.

Enables a quick and reliable DNS server provided by Yandex.

The DNS IP addresses (IPv4) are the following:

• 77.88.8.8
• 77.88.8.1

Note, that the parameter conflicts with ENABLE_GOOGLE_DNS, ENABLE_FAMILY_YANDEX_DNS and ENABLE_CUSTOM_DNS.

Enables the DNS server provided by Yandex with protection from "adult" content.

• 77.88.8.7
• 77.88.8.3

Note, that the parameter conflicts with ENABLE_GOOGLE_DNS, ENABLE_BASIC_YANDEX_DNS, and ENABLE_CUSTOM_DNS.

Enables a custom DNS server specified via this parameter.

Note, that the parameter conflicts with ENABLE_GOOGLE_DNS, ENABLE_BASIC_YANDEX_DNS, and ENABLE_FAMILY_YANDEX_DNS.

Specifies the hostname of a device.

Allows installing packages without checking their signatures.

This is an Alpine-specific parameter. It enables the community repository.

This is a Debian-specific parameter. It enables the non-free and contrib sections in /etc/apt/sources.list. By default, only the main section is used. Sections are also called components or areas.

Allows installing packages without prompting the user to answer any questions.

This is an Ubuntu-specific parameter. It enables the universe section in /etc/apt/sources.list. By default, only the main section is used.

A comma-separated list of the packages to be installed on the system specified via OS.

Installs sudo. If ENABLE_USER is set to true, Pieman adds the user USER_NAME to /etc/sudoers.

Creates a non-root user USER_NAME with the password USER_PASSWORD.

Allows specifying the root password. It's HIGHLY RECOMMENDED to change the default root password.

If PASSWORD equals to -, Pieman will prompt for a password, and read it without echoing to screen.

Tells sudo whether it should prompt for the password.

It's necessary to disable the password prompts if you want to manage your device via, for example, SSH Button.

Allows specifying a non-root user name. It's ignored if ENABLE_USER is set to false.

Allows specifying a non-root user password. It's ignored if ENABLE_USER is set to false. It's HIGHLY RECOMMENDED to change the default user password.

If USER_PASSWORD equals to -, Pieman will prompt for a password, and read it without echoing to screen.

Compresses the resulting image using bzip2.

Note, that the parameter conflicts with COMPRESS_WITH_GZIP and COMPRESS_WITH_XZ.

Compresses the resulting image using gzip.

Note, that the parameter conflicts with COMPRESS_WITH_BZIP2 and COMPRESS_WITH_XZ.

Compresses the resulting image using xz.

Note, that the parameter conflicts with COMPRESS_WITH_BZIP2 and COMPRESS_WITH_GZIP.

Allows specifying the ownership of the target image (see PROJECT_NAME) and project directory (see BUILD_DIR). By default, the ownership is borrowed from pieman.sh which, as a rule, belongs to a regular user.

Note, that the parameter must follow the format "uid:gid" where uid and gid are numbers.

Allows specifying the Python 3 interpreter to be used when calling the Pieman-specific utilities.

You can find the images of all supported operating systems for all supported devices here. Login username is cusdeb, password is secret.

See AUTHORS.

Pieman is available under the GNU General Public License version 3.

Pieman borrows some pieces of code from rpi23-gen-image which are available under the GNU General Public License version 2.

If you want to contribute to Pieman, we encourage you to do so by sending a pull request.

In case you encounter any issues, please feel free to raise a ticket!

If you like Pieman and want to support it, then please star the project or watch it on GitHub.