Skip to content

Home

Jump to bottom
Pete Fotheringham edited this page Feb 2, 2025 · 22 revisions

Welcome to the docker-lineage-cicd wiki!

Using the Docker Image

Why Docker?

A fair number of dependencies is needed to build LineageOS, plus a Linux system (and a discrete knowledge of it). With Docker we give you a minimal Linux build system with all the tools and scripts already integrated, easing considerably the creation of your own LineageOS build.

Moreover Docker runs also on Microsoft Windows and Mac OS, which means that LineageOS can be built on such platforms without requiring a dual boot system or a manual set up of a Virtual Machine.

How do I install Docker?

The official Docker guides are well-written:

Life is considerably easier if you setup Docker to allow execution by non-root users: see 'Run the Docker daemon as a non-root user'

If your Windows or Mac system doesn't satisfy the requirements (or if you have Oracle VirtualBox installed, you can use Docker Toolbox. Docker Toolbox is not described in this guide, but it should be very similar to the standard Docker installation.

Once you can run the hello-world image you're ready to start!

What does Docker build

Docker will produce the following files in the zips directory:

  • the main ROM zip file e.g. lineage-20.0-20230702-microG-<device-name>.zip. This file can be flashed from recovery as described in the next section
  • a custom recovery image (e.g. lineage-20.0-20230702-microG-<device-name>-recovery.img or lineage-20.0-20230702-microG-<device-name>-boot.img) and any other images needed or mentioned in the LineageOS installation instructions;
    • if the ZIP_UP_IMAGES environment variable is set true, these images will be zipped up into an -images.zip file e.g. lineage-20.0-20230702-microG-<device-name>-images.zip
    • else, if the MAKE_IMG_ZIP_FILE environment variable is set true the images are zipped into a flashable ...-img.zip file (e.g. lineage-20.0-20230702-microG-<device-name>-img.zip) which can be installed using fastboot flash or fastboot update

Docker can build the following ROMs (See Examples for more details)

How can I build LineageOS?

Before you start, make sure you have the latest version of our Docker image:

docker pull lineageos4microg/docker-lineage-cicd

The requirements for building LineageOS for MicroG are roughly the same as for building LineageOS:

  • A relatively recent x86_64 computer:

    • Linux, macOS, or Windows - these instructions are only tested using Ubuntu 20.04 LTS, so we recommend going with that.
    • A reasonable amount of RAM (16 GB to build up to lineage-17.1, 32 GB or more for lineage-18.1 and up). The less RAM you have, the longer the build will take. Enabling ZRAM can be helpful. If builds fail because of lack of memory, you can sometimes get over the problem by increasing the amount of swap, but this will be at the expense of slower build times.
    • A reasonable amount of Storage (~300 GB for lineage-18.1 and up). You might require more free space for enabling ccache, building for multiple devices, or if you choose to mirror the LineageOS sources (see below). Using SSDs results in considerably faster build times than traditional hard drives.

  • A decent internet connection and reliable electricity. :)

  • Some familiarity with basic Android operation and terminology. It may be useful to know some basic command line concepts such as cd, which stands for “change directory”, the concept of directory hierarchies, and that in Linux they are separated by /, etc.

This Docker image contains a great number of settings, to allow you to fully customize your LineageOS build. Here you can find all of them, with the default values between the brackets.

TL;DR - go to the Examples

Fundamental settings

The two fundamental settings are:

  • BRANCH_NAME (lineage-16.0): LineageOS branch, see the branch list here (multiple comma-separated branches can be specified)
  • DEVICE_LIST: comma-separated list of devices to build

Running a build with only these two set will create a ZIP file almost identical to the LineageOS official builds, just signed with the test keys.

When multiple branches are selected, use DEVICE_LIST_<BRANCH_NAME> to specify the list of devices for each specific branch (see the examples).

GMS / microG

To include microG (or possibly the actual Google Mobile Services) in your build, LineageOS expects certain Makefiles in vendor/partner_gms and variable WITH_GMS set to true.

This repo contains the common packages included for official lineageos4microg builds. To include it in your build, create an XML (the name is irrelevant, as long as it ends with .xml) in the /home/user/manifests folder with this content:

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <project path="vendor/partner_gms" name="lineageos4microg/android_vendor_partner_gms" remote="github" revision="master" />
</manifest>

Additional custom apps

If you wish to add other apps to your ROM, you can include a repository with source code or prebuilt APKs. For prebuilt apks, see the android_vendor_partner_gms repository for examples on how the Android.mk file should look like.

Include the repo with another manifest file like this:

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <project name="your-github-user/your-repo" path="prebuilts/my-custom-apps" remote="github" revision="master" />
</manifest>

And when starting the build, set the CUSTOM_PACKAGES variable to a list of app names (defined by LOCAL_MODULE in Android.mk) separated by spaces.

Signature spoofing

Please read this post in the microG GmsCore wiki for an explanation of Signature spoofing. Until February 2025, official LineageOS ROMs did not support signature spoofing. Before then LineageOS had refused requests to support sgnature spoofing, because

it isn't our place to lie about security features.

For LineageOS for microG to work, we had to patch the LineageOS source code to allow microG GmsCore to spoof the existence of the official Play Services to applications calling Google APIs. The SIGNATURE_SPOOFING environment variable was used when building our ROMs, so that the correct patches could be applied to the LineageOS sources.

In February 2025, LineageOS added support for signature spoofing in LineageOS versions 18.1, 19.1, 20.0 and 21.0. This support only allows microG to spoof its signature; no other apps are allowed to do so. This 'restricted' signature spoofing is enough for LineageOS for microG builds to work, so we did not create patches for the lineage-22.1, and the patches for earlier versions are not used, not maintained, and - since Google made changes to the signature checking code in December 2024 - will probably no longer work.

If anyone wanted to try to use the patches, the following information, now out of date, may be useful:

Outdated information

Two custom signature spoofing patches are provided:

  • "Original" patches
  • Restricted patches

With the "original" patch the FAKE_SIGNATURE permission can be granted to any user app: while it may seem handy, this is considered dangerous by a great number of people, as the user could accidentally give this permission to rogue apps.

A more strict option is the restricted patch, where the FAKE_SIGNATURE permission can be obtained only by privileged system apps, embedded in the ROM during the build process.

The custom signature spoofing patch can be optionally included with:

  • SIGNATURE_SPOOFING (no): yes to use the original patch, restricted for the restricted one, no for none of them and to default to built-in signature spoofing.

If in doubt, use restricted: note that packages that requires the FAKE_SIGNATURE permission must be included in the build as system apps (e.g. as part of GMS or CUSTOM_PACKAGES)

These patches are currently disabled for LineageOS 21 entirely. If you have an use case which requires the use of custom patches on 21, please open an issue.

End of outdated information

Proprietary files

Some proprietary binary files are needed to create a LineageOS build: these are components that

  • are not open source, so cannot be built from source for our builds
  • are device-specific: they are often low-level libraries drivers for hardware components
  • have to be extracted from the device-specific software and firmware shipped by the manufacturer
  • are often referred to as 'blobs'

The extraction process is complicated and error prone. The easiest way to include them in builds of devices that are - or have been - officially supported by LineageOS, is to use the versions which are stored in TheMuppets GitHub and GitLab repositories. These repositories are used in our builds and in official LineageOS builds, but are not included in the LineageOS repositories for legal reasons.

Using TheMuppets repositories is easy, and is enabled by default: the INCLUDE_PROPRIETARY variable is set 'true' in the Dockerfile

If you want to try extracting them yourself - perhaps to build for a device not supported by LineageOS - then LineageOS provide documentation on

If you don't want or need to use TheMuppets repositories, set INCLUDE_PROPRIETARY to false and provide a manifest pointing to a repository containing the blobs you will use instead (see Examples).

Over the Air updates

To enable OTA for you builds, you need to run a server that speaks the protocol understood by the LineageOS updater app and provide the URL to this server as OTA_URL variable for the build.

One implementation is LineageOTA, which is also available as Docker image. Follow these steps to prepare your builds for OTA:

  • Run the Docker image julianxhokaxhiu/lineageota
    • Port 80 exposed to the internet (might want to add an HTTPS reverse proxy)
    • The /srv/zips directory/volume of the CICD image mounted at /var/www/html/builds/full (can be read-only)
  • Set environment variables when building
    • ZIP_SUBDIR to false
    • OTA_URL to the address of the OTA server, with /api appended

If you don't setup a OTA server you won't be able to update the device from the updater app (but you can still update it manually with the recovery of course).

Signing

By default, builds are signed with the Android test keys. If you want to sign your builds with your own keys (highly recommended):

  • SIGN_BUILDS (false): set to true to sign the builds with the keys contained in /srv/keys; if no keys are present, a new set will be generated

Settings to control 'switchable' build steps

Some of the the steps in the build process (e.g repo sync, mka) can take a long time to complete. When working on a build, it may be desirable to skip some of the steps. The following environment variables (and their default values) control whether or not each step is performed

# variables to control whether or not tasks are implemented
ENV INIT_MIRROR true
ENV SYNC_MIRROR true
ENV RESET_VENDOR_UNDO_PATCHES true
ENV CALL_REPO_INIT true
ENV CALL_REPO_SYNC true
ENV CALL_GIT_LFS_PULL false
ENV APPLY_PATCHES true
ENV PREPARE_BUILD_ENVIRONMENT true
ENV CALL_BREAKFAST true
ENV CALL_MKA true
ENV ZIP_UP_IMAGES false
ENV MAKE_IMG_ZIP_FILE false

To switch an operation, change the default value of the the variable in a -e clause in the docker run command e.g. -e "CALL_REPO-SYNC=false" \

The ZIP_UP_IMAGES and MAKE_IMG_ZIP_FILE variables control how the .img files created by the buid are handled:

  • by default, the img files are copied - unzipped - to the zips directory
  • if ZIP_UP_IMAGES is set true, the images are zipped and the resulting ...images.zip is copied to the zips directory
  • if MAKE_IMG_ZIP_FILE is set true, a flashsable ...-img.zip file is created, which can be installed using fastboot flash or fastboot update

Other settings

Other useful settings are:

  • CCACHE_SIZE (50G): change this if you want to give more (or less) space to ccache
  • RELEASE_TYPE (UNOFFICIAL): change the release type of your builds
  • BUILD_TYPE (userdebug): type of your builds, see Android docs
  • BUILD_OVERLAY (false): normally each build is done on the source tree, then the tree is cleaned with mka clean. If you want to be sure that each build is isolated from the others, set BUILD_OVERLAY to true (longer build time). Requires --cap-add=SYS_ADMIN. (As the time of writing - 27 January 2025 - this setting does not work: setting BUILD_OVERLAY=true will cause the build to fail with an error message).
  • LOCAL_MIRROR (false): change this to true if you want to create a local mirror of the LineageOS source (> 200 GB)
  • CRONTAB_TIME (now): instead of building immediately and exit, build at the specified time (uses standard cron format)
  • ZIP_SUBDIR (true): Move the resulting zips to $ZIP_DIR/$codename instead of $ZIP_DIR/
  • PARALLEL_JOBS: Limit the number of parallel jobs to run (-j for repo sync and mka). By default, the build system should match the number of parallel jobs to the number of cpu cores on your machine. Reducing this number can help keeping it responsive for other tasks.
  • RETRY_FETCHES: Set the number of retries for the fetch during repo sync. By default, this value is unset (default repo sync retry behavior). Positive values greater than 0 are allowed.

The full list of settings, including the less interesting ones not mentioned in this guide, can be found in the Dockerfile.

Volumes

You also have to provide Docker some volumes, where it'll store the source, the resulting builds, the cache and so on. The volumes are:

  • /srv/src, for the LineageOS sources
  • /srv/zips, for the output builds
  • /srv/logs, for the output logs
  • /srv/ccache, for the ccache
  • /srv/local_manifests, for custom manifests (optional)
  • /srv/userscripts, for the user scripts (optional)

When SIGN_BUILDS is true

  • /srv/keys, for the signing keys

When BUILD_OVERLAY is true

  • /srv/tmp, for temporary files

When LOCAL_MIRROR is true:

  • /srv/mirror, for the LineageOS mirror

These volumes do not need to be in the same directory tree: you specify the directories that Docker will use for these volumes in the docker run ... command.

Examples

All these examples use the directory /home/user/work as the base directory for the volumes. Amend the commands as required to fit your working setup.

Build for a device officially supported by LineageOS

LineageOS for microG

  • building the lineage-22.1 branch - see https://github.com/LineageOS/android/branches for possible options
  • WITH_GMS=true to include the makefiles and components from the android_vendor_partner_gms repository
  • local manifest pointing to the android_vendor_partner_gms repository
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <project path="vendor/partner_gms" name="lineageos4microg/android_vendor_partner_gms" remote="github" revision="master" />
</manifest>
  • INCLUDE_PROPRIETARY=true to use the proprietary vendor blobs from TheMuppets GitHub repos. This is not really needed in the command as it is the default value set in Dockerfile
  • Sony Xperia 1 III codename: pdx215
docker run \
    -e "BRANCH_NAME=lineage-22.1" \
    -e "DEVICE_LIST=pdx215" \
    -e "WITH_GMS=true" \
    -e "INCLUDE_PROPRIETARY=true" \
    -v "/home/user/lineage:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
    lineageos4microg/docker-lineage-cicd
  • to build for more than one device, add the device names, separated by commas, to the DEVICE_LIST line e.g.
    -e "DEVICE_LIST=pdx215,pdx234,pdx237" \

LineageOS

  • as for LineageOS for microG except
  • WITH_GMS=false. This is not really needed in the command as it is the default value set in Dockerfile
  • don't need the local manifest pointing to the android_vendor_partner_gms repository
docker run \
    -e "BRANCH_NAME=lineage-22.1" \
    -e "DEVICE_LIST=pdx215" \
    -e "WITH_GMS=false" \
    -v "/home/user/lineage:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
    lineageos4microg/docker-lineage-cicd

IodéOS

  • as for LineageOS, but use the :pf-build-iodeOS tag
  • use the IodéOS branches (see https://gitlab.iode.tech/os/public/manifests/android/-/branches). v5 is Android 14 / LineageOS 21.0. (At the time of writing - January 2025 - that is the latest official branch of IodéOS)
  • this example uses /home/user/iode for the src volume, but as noted above, any directory can be used
  • building with WITH_GMS=false (the default) is usually fine: WITH_GMS is not needed to pull in the microG, F-Droid and other components, as they are included in the IodéOS sources and manifests. Some devices use WITH_GMS to change the amount of space reserved for different partitions (see e.g. here or here). If your build fails with e.g. errors in partition sizes, setting WITH_GMS=true may allow it to succeed. An alternative approach to fixing such errors is to set values explicitly. These can be configured for e.g.BOARD_PRODUCTIMAGE_PARTITION_RESERVED_SIZE, BOARD_SYSTEMIMAGE_PARTITION_RESERVED_SIZE, BOARD_SYSTEM_EXTIMAGE_PARTITION_RESERVED_SIZE by setting environment variables ( -e ... lines in the docker run ... command) which will override values set in makefiles. e.g
    -e "BOARD_SYSTEM_EXTIMAGE_PARTITION_RESERVED_SIZE=94371840" \
  • this will pick up the vendor blobs from TheMuppets because the default value for INCLUDE_PROPRIETARY is true 
docker run \
    -e "BRANCH_NAME=v5.8" \
    -e "DEVICE_LIST=pdx215" \
    -v "/home/user/iode:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
    lineageos4microg/docker-lineage-cicd:pf-build-iodeOS

Build for a device not officially supported by LineageOS

  • local manifest pointing to
    • device and kernel sources, as they are not in the LineageOS repositories
    • proprietary vendor blobs, as they are not in the TheMuppets repositories
    • this example picks up everything needed to build the Sony Xperia devices based on the Yoshino platform (XZ1 poplar & poplar_dsds, XZ1 Compact lilac, XZ Premium maple & maple_dsds), from the repos used to make unofficial LineageOS builds for these devices. At the time of writing (January 2025) Android 14 / lineage-21.0 is the latest branch available in those repos
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <!-- kernel -->
  <project name="whatawurst/android_kernel_sony_msm8998" path="kernel/sony/msm8998" remote="github" revision="lineage-21" />

  <!-- device trees -->
  <project name="whatawurst/android_device_sony_yoshino-common" path="device/sony/yoshino-common" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_device_sony_maple" path="device/sony/maple" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_device_sony_maple_dsds" path="device/sony/maple_dsds" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_device_sony_poplar" path="device/sony/poplar" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_device_sony_poplar_dsds" path="device/sony/poplar_dsds" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_device_sony_lilac" path="device/sony/lilac" remote="github" revision="lineage-21" />

  <!-- binary blobs  -->
  <project name="whatawurst/android_vendor_sony_maple" path="vendor/sony/maple" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_vendor_sony_maple_dsds" path="vendor/sony/maple_dsds" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_vendor_sony_poplar" path="vendor/sony/poplar" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_vendor_sony_poplar_dsds" path="vendor/sony/poplar_dsds" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_vendor_sony_lilac" path="vendor/sony/lilac" remote="github" revision="lineage-21" />
  <project name="whatawurst/android_vendor_sony_yoshino-common" path="vendor/sony/yoshino-common" remote="github" revision="lineage-21" />

</manifest>

LineageOS for microG

  • use WITH_GMS=true and the local manifest pointing to the android_vendor_partner_gms repository
  • INCLUDE_PROPRIETARY=false - get the vendor blobs from the repos specified in the manifest
  • build for all variants of the devices, single-SIM and dual-SIM
docker run \
    -e "BRANCH_NAME=lineage-21.0" \
    -e "DEVICE_LIST=lilac,poplar,poplar_dsds,maple,maple_dsds" \
    -e "WITH_GMS=true" \
    -e "INCLUDE_PROPRIETARY=true" \
    -v "/home/user/lineage:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
    lineageos4microg/docker-lineage-cicd

LineageOS

  • same local manifest for device and kernel sources and proprietary vendor blobs
  • as for official devices (WITH_GMS=false, no local manifest pointing to the android_vendor_partner_gms repository)
  • INCLUDE_PROPRIETARY=false - get the vendor blobs from the repos specified in the manifest
docker run \
    -e "BRANCH_NAME=lineage-21.0" \
    -e "DEVICE_LIST=lilac,poplar,poplar_dsds,maple,maple_dsds" \
    -e "WITH_GMS=false" \
    -e "INCLUDE_PROPRIETARY=false" \
    -v "/home/user/lineage:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
    lineageos4microg/docker-lineage-cicd

IodéOS

  • same local manifest for device and kernel sources and proprietary vendor blobs
  • as for official devices (WITH_GMS=false, no local manifest pointing to the android_vendor_partner_gms repository, IodéOS branch names, use the :pf-build-iodeOS tag)
  • INCLUDE_PROPRIETARY=false - get the vendor blobs from the repos specified in the manifest
docker run \
    -e "BRANCH_NAME=lineage-21.0" \
    -e "DEVICE_LIST=lilac,poplar,poplar_dsds,maple,maple_dsds" \
    -e "WITH_GMS=false" \
    -e "INCLUDE_PROPRIETARY=false" \
    -v "/home/user/lineage:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
    lineageos4microg/docker-lineage-cicd:pf-build-iodeOS

Handling build problems

See also `Build errors, fixes and work arounds' in my personal project wiki

Build killed with 'out of memory errors

To be written

Clone this wiki locally