The typical way to install Endless OS is to download an ISO or disk image built by Endless, which includes a generic set of applications and content. In some circumstances a custom image might be preferred. A typical use case would be adding or removing applications.
The Endless OS image builder is the tool used by Endless to create images for installation and evaluation. The tool has a rich set of customization methods to alter the content of the images and produce the expected assets. Some basic instructions and examples are given below, but please consult the image builder README for full details on how the configuration and hooks layers can be used to customize the build.
The Endless OS image builder is intended for use by advanced users, technicians and developers. Producing custom Endless OS images with this tool requires a degree of technical prowess and attention to detail, particularly when more advanced customisations are required.
The Endless OS image builder was only recently released for public use, it is a work in progress and we intend to make it more usable and accessible in future. Please be aware of the following restrictions and caveats:
ostree installed on the host; to build Endless OS 5.0 or older, you need gpg and mmdebstrap. (Endless OS 4 and newer contain all the necessary tools.)podman or toolbox container.eos-image-builder repo and enter it:git clone https://github.com/endlessm/eos-image-builder.git
cd eos-image-builder
config/local.ini file as needed. Some typical customizations can be seen in config/local.ini.example.sudo ./eos-image-builder
Currently the builder needs to run privileged to create the build root and loop devices. The easiest way to do that is to run as root, as instructed above.
When completed, the built images can be found in /var/cache/eos-image-builder/tmp/out. The entire /var/cache/eos-image-builder directory can be deleted when no longer needed, but it will cache some resources for reuse on subsequent builds if you plan to create more images.
Images built with this tool include Endless OS (more precisely: the Endless OS ostree filesystem tree), a copyrighted collective work of the Endless OS Foundation, and hence any redistribution of such images is subject to the Endless OS Redistribution Policy.
This eos-image-builder tool in itself is Open Source software licensed under the GNU GPL v2.
Below are some typical customizations available.
By default the image builder creates images based on the unreleased master branch of the OS. This can be changed by passing a different branch on the command line. Note that the image builder is branched at the same time as the OS so that changes to the image builder can be managed independently for each OS branch.
For that reason it's required to checkout the image builder branch matching the OS branch to build from. For example, to build eos4.0:
git checkout eos4.0
sudo ./eos-image-builder --use-production-ostree eos4.0
--use-production-ostree instructs the image builder to use the released version of the OS, rather than a nightly build. If you want to build an image that uses the unreleased nightly build of the OS, omit that argument.
The image builder chooses from a set of configurations in the config directory based on the command line options. The typical configuration option to change for customization is referred to as the personality and is set by the --personality option. By default this is base, which is a minimal installation with few applications. Other personalities include en, which includes a standard set of configuration, apps and content targeted at English language speakers. Specifying --personality en will choose this personality. You can also define your own personality by creating a new file in config/personality.
The set of applications to install can be changed with local configuration settings in config/local.ini. For example:
[flatpak-remote-flathub]
apps_add =
com.valvesoftware.Steam
org.ardour.Ardour
apps_del =
edu.mit.Scratch
This would add Steam and Ardour from Flathub while removing Scratch. Another method is to completely override the set of applications for a given remote:
[flatpak-remote-flathub]
apps = org.mozilla.firefox
To override the default app grid layout, create a file called data/icon-grid/icon-grid-C.json as a copy of /usr/share/eos-shell-content/icon-grid-defaults/icon-grid-C.json, and adjust it to your needs. In brief, the "desktop" key contains the list of apps and folders to show at the top-level, across as many pages as needed. Other keys, such as "eos-folder-play.directory", describe the contents of folders; you must place the folder name as an item in the "desktop" list for it to appear.
Having done this, add the following to your personality configuration:
[image]
icon_grid_add = data/icon-grid/icon-grid-C.json
If you wish to have different layouts for different languages, create additional files named using the appropriate language or locale code, such as icon-grid-fr.json for French, icon-grid-pt_BR.json for Brazilian Portuguese, etc. Then list all these files in your personality configuration:
[image]
icon_grid_add = data/icon-grid/icon-grid-C.json
data/icon-grid/icon-grid-fr.json
data/icon-grid/icon-grid-pt_BR.json
The C layout is used as a fallback if there is no specific configuration for the user's locale.
The apps and folders listed in the "desktop" key will be placed across as many pages as needed. If there are any apps remaining which are not on those pages or in a folder, they will be added on subsequent pages.
Since Endless OS 4.0.1, you can arrange your desktop app grid as you like it, then run:
eos-save-icon-grid
to export it as a JSON file plus collection of .directory files.
Since Endless OS 5, any app that is shown on the dock is not shown in the app grid. If you want to place App Center, Chromium, or Files on the app grid rather than on the dock, see the Default favourite apps section below.
Any .directory files mentioned in the custom grid layout must be installed in the OS. There are a number of built-in directories in /usr/share/desktop-directories, and we suggest using these names if possible.
Otherwise, you currently need a custom image hook to install additional .directory files. One way is to create (e.g.) hooks/image/51-desktop-folders.chroot:
TARGET_PATH=/usr/local/share/desktop-directories
mkdir -p ${TARGET_PATH}
cat <<EOF > ${TARGET_PATH}/folder-music.directory
[Desktop Entry]
Version=1.0
Name=Music
Name[es]=Música
Name[fr]=Musique
Type=Directory
EOF
Then configure the builder to run this hook:
[image]
hooks_add =
51-desktop-folders.chroot
By default, three apps are shown on the dock (or taskbar in Endless OS 4) by default:
org.gnome.Software.desktop)org.chromium.Chromium.desktop)org.gnome.Nautilus.desktop)To override this, create a file named data/settings/favorite-apps with contents like the following:
[org/gnome/shell]
favorite-apps=['org.gnome.Software.desktop', 'org.chromium.Chromium.desktop', 'org.tuxpaint.Tuxpaint.desktop']
In your personality configuration, add the following reference to this file:
[image]
settings_add = data/settings/favorite-apps
The example above removes Files from the default favourites, and adds Tuxpaint.
You can override other GSettings in the same way. Take care: the file format uses the syntax accepted by dconf compile, not the syntax of GSettings vendor overrides. You can list all the settings for your user with the following command:
dconf dump / | less
It can be worthwhile to include Kolibri content in an image. To specify Kolibri channels for a personality, add a [kolibri] section in the personality configuration:
[kolibri]
install_channels =
# How to get started with Kolibri on Endless OS [62]
e8a879742b2249a0a4b890f9903916f7
You can include specific content from the included channels, as well, by adding a section for each channel:
[kolibri-e8a879742b2249a0a4b890f9903916f7]
include_node_ids =
# How to get started with Kolibri on Endless OS [topic - 62]
e8a879742b2249a0a4b890f9903916f7
For more complex needs, try eos-kolibri-listcontent to generate Kolibri content configuration:
It is often convenient to use an ISO image to test & install Endless OS. You can configure the image builder to generate an ISO image as follows:
[image]
iso = true
(This is disabled by default since it makes the image builder take longer to run and roughly doubles the disk space required for the final artefacts.)
Images downloaded from Endless are signed with GPG to provide verification to users. A custom GPG key can be provided to generate signatures for each assets.
First, specify the GPG key ID in config/local.ini:
[image]
signing_keyid = 0123456789ABCDEF
Next, create the image builder's GPG home directory and import the private key.
sudo mkdir -p /etc/eos-image-builder/gnupg
sudo chmod 700 /etc/eos-image-builder/gnupg
sudo gpg --homedir /etc/eos-image-builder/gnupg import /path/to/private/key