forked from brl/citadel
114 lines
4.8 KiB
Plaintext
114 lines
4.8 KiB
Plaintext
Application Image Builder
|
|
=========================
|
|
|
|
Application Images (or appimgs for short) are created with this builder
|
|
framework. The build is controlled by a configuration file which can customize
|
|
the build process in various ways such as adding extra packages and specifying
|
|
shell functions to be run at certain stages.
|
|
|
|
The configuration file is really just a shell script but it should follow the
|
|
conventions described in the Configuration File section of this document.
|
|
|
|
The builder bind mounts a package cache directory into /var/cache/apt of the
|
|
chroot so packages will only need to be downloaded once no matter how many times
|
|
you repeat the build. As a nice consequence of this the cached packages don't have
|
|
to be removed from the final image because they are merely unmounted when the
|
|
process completes.
|
|
|
|
Unless you disable it with a command line option, a tmpfs will be mounted on the
|
|
directory the rootfs is built on.If you are tweaking a config and making repeated
|
|
builds this is not only a lot faster, but will also avoid hammering SSD drives with
|
|
excessive writes (and write amplification).
|
|
|
|
By default the application image builder is self-hosting and can always be
|
|
run from inside images that it creates. Building an image is as easy as:
|
|
|
|
mkdir work && cd work : Make a directory to work in
|
|
appimg-builder --new : writes a template file build.conf in current directory
|
|
vim build.conf : (optionally) make some changes to the template
|
|
sudo appimg-build : Build an application image
|
|
|
|
If you want you can even skip the steps of creating and editing a config file and
|
|
just run appimg-build in a work directory and it will build the default appimg we use
|
|
with Citadel.
|
|
|
|
Stage One
|
|
---------
|
|
|
|
The Stage One builder uses debootstrap to build a very minimal debian
|
|
installation. Then a chroot is set up and stage-two.sh is executed inside the
|
|
chroot to perform most of the installation.
|
|
|
|
Stage Two
|
|
---------
|
|
|
|
The stage-two.sh script mostly just orchestrates the execution of small
|
|
fragments of shell script code that are called 'modules'. The base framework
|
|
modules can be found in the directory /usr/share/appimg-builder/appimg-modules.
|
|
|
|
It imports the configuration file with the 'source' command after all the key
|
|
variables and functions have been defined. It's possible to override any of
|
|
these variables and functions simply by defining another version with the same
|
|
name in the configuration file, but you should almost never need to do this.
|
|
|
|
Configuration File
|
|
------------------
|
|
|
|
- Variables
|
|
|
|
PACKAGES can be set to a list of additional packages to add to the base set of
|
|
packages.
|
|
|
|
PACKAGES="extremetuxracer biff anarchism"
|
|
|
|
PRE_INSTALL_MODULES can be set to a list of modules to run before the main
|
|
package installation stage happens. The contents will be appended to a
|
|
pre-defined list of 'base' modules that run.
|
|
|
|
PRE_INSTALL_MODULES="my-cool-module another-module"
|
|
|
|
If complete control over the modules to run is required, you can override the
|
|
variable BASE_PRE_INSTALL_MODULES entirely rather than providing
|
|
PRE_INSTALL_MODULES. Other modules depend on 'utility-library' so it is usually
|
|
required and should be the first module listed.
|
|
|
|
BASE_PRE_INSTALL_MODULES="utility-library configure-locale custom-create-user"
|
|
|
|
POST_INSTALL_MODULES is a list of modules to execute after packages have been
|
|
installed. It works exactly the same way as PRE_INSTALL_MODULES and also has a
|
|
corresponding 'base' variable that could be overidden if necessary.
|
|
|
|
- Modules
|
|
|
|
Modules can be functions that you define or they can be loaded from files on
|
|
disk. To use files rather than functions a directory named 'appimg-modules'
|
|
must exist as a subdirectory of the directory containing the configuration file.
|
|
Any files you place in this directory will be found by name during the module
|
|
execution stages.
|
|
|
|
- Installing Files
|
|
|
|
If you would like to have external files such as configuration files copied into
|
|
the image, create 'appimg-files' as a subdirectory of the directory containing
|
|
the configuration file. You can then use the install_file command inside of a
|
|
module to copy the files from this directory. You can either store the files to
|
|
install in a flat directory or organize them into subdirectories mirroring the
|
|
location in which they will be installed. Depending on which option you use,
|
|
the install_file command how two different modes. In the examples below BASE
|
|
refers to the directory in which your configuration file is located.
|
|
|
|
(1): install_file [mode] [file] [target directory]
|
|
|
|
Example: Install BASE/appimg-files/my_config.conf
|
|
to /etc/mydaemon/my_config.conf
|
|
|
|
install_file 0644 my_config.conf /etc/mydaemon
|
|
|
|
(2): install_file [mode] [full path]
|
|
|
|
Example: Install BASE/appimg-files/etc/mydaemon/my_config.conf
|
|
to /etc/mydaemon/my_config.conf
|
|
|
|
install_file 0644 /etc/mydaemon/my_config.conf
|
|
|