search

lineageos4microg / docker-lineage-cicd

Docker microservice for LineageOS Continuous Integration and Continous Deployment
https://hub.docker.com/r/lineageos4microg/docker-lineage-cicd
GNU General Public License v3.0
480 stars 189 forks source link

readme

docker-lineage-cicd

Docker microservice for LineageOS Continuous Integration and Continuous Deployment

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:

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 two files in the zips directory:

  1. 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.
  2. A -image.zip file e.g. lineage-20.0-20230702-microG-<device-name>-images.zip, containing a custom recovery image and any other images needed or mentioned in the LineageOS installation instructions.

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:

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:

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

For LineageOS versions 18.1, 19.1, 20.0 and 21.0, built-in support for signature spoofing has been added. This specifically only allows microG to spoof its signature; no other apps are allowed to do so. If this is fine, the SIGNATURE_SPOOFING environment variable may be left unset (defaulting to no).

If not, two custom signature spoofing patches are provided:

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:

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.

Proprietary files

Some proprietary files are needed to create a LineageOS build, but they're not included in the LineageOS repo for legal reasons. You can obtain these blobs in three ways:

The third way is the easiest one and is enabled by default; if you're OK with that just move on, otherwise set INCLUDE_PROPRIETARY (true) to false and manually provide the blobs (not explained in this guide).

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:

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):

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:

Other settings

Other useful settings are:

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:

When SIGN_BUILDS is true

When BUILD_OVERLAY is true

When LOCAL_MIRROR is true:

Examples

Build for river (lineage-18.1, officially supported), test keys, no patches

docker run \
    -e "BRANCH_NAME=lineage-18.1" \
    -e "DEVICE_LIST=river" \
    -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

Build for bacon (lineage-17.1, officially supported), custom keys, restricted signature spoofing with integrated microG and FDroid

docker run \
    -e "BRANCH_NAME=lineage-17.1" \
    -e "DEVICE_LIST=bacon" \
    -e "SIGN_BUILDS=true" \
    -e "SIGNATURE_SPOOFING=restricted" \
    -e "WITH_GMS=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" \
    -v "/home/user/keys:/srv/keys" \
    -v "/home/user/manifests:/srv/local_manifests" \
    lineageos4microg/docker-lineage-cicd

If there are already keys in /home/user/keys they will be used, otherwise a new set will be generated before starting the build (and will be used for every subsequent build).

The microG and FDroid packages are not present in the LineageOS repositories, and must be provided e.g. through android_vendor_partner_gms.

Build for four devices on lineage-17.1 and lineage-18.1 (officially supported), custom keys, restricted signature spoofing with integrated microG and FDroid, custom OTA server

docker run \
    -e "BRANCH_NAME=lineage-17.1,lineage-18.1" \
    -e "DEVICE_LIST_LINEAGE_17_1=bacon,oneplus2" \
    -e "DEVICE_LIST_LINEAGE_18_1=river,lake" \
    -e "SIGN_BUILDS=true" \
    -e "SIGNATURE_SPOOFING=restricted" \
    -e "WITH_GMS=true" \
    -e "OTA_URL=https://api.myserver.com/" \
    -v "/home/user/lineage:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
    -v "/home/user/keys:/srv/keys" \
    -v "/home/user/manifests:/srv/local_manifests" \
    lineageos4microg/docker-lineage-cicd

Build for a6000 (not officially supported), custom keys, restricted signature spoofing with integrated microG and FDroid

As there is no official support for this device, we first have to include the sources in the source tree through an XML in the /home/user/manifests folder; from this thread we get the links of:

Then, with the help of lineage.dependencies from the device tree and the common tree we create an XML /home/user/manifests/a6000.xml with this content:

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <project name="dev-harsh1998/android_device_lenovo_a6000" path="device/lenovo/a6000" remote="github" />
  <project name="dev-harsh1998/android_device_lenovo_msm8916-common" path="device/lenovo/msm8916-common" remote="github" />
  <project name="dev-harsh1998/kernel_lenovo_msm8916" path="kernel/lenovo/a6000" remote="github" />
  <project name="dev-harsh1998/proprietary-vendor_lenovo" path="vendor/lenovo" remote="github" />
  <project name="LineageOS/android_device_qcom_common" path="device/qcom/common" remote="github" />
</manifest>

We also want to include microG so, like before, create an XML (for example /home/user/manifests/microg.xml) 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>

We also set INCLUDE_PROPRIETARY=false, as the proprietary blobs are already provided by the repo https://github.com/dev-harsh1998/prorietary_vendor_lenovo (so we don't have to include the TheMuppets repo).

Now we can just run the build like it was officially supported:

docker run \
    -e "BRANCH_NAME=lineage-15.1" \
    -e "DEVICE_LIST=a6000" \
    -e "SIGN_BUILDS=true" \
    -e "SIGNATURE_SPOOFING=restricted" \
    -e "WITH_GMS=true" \
    -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" \
    -v "/home/user/keys:/srv/keys" \
    -v "/home/user/manifests:/srv/local_manifests" \
    lineageos4microg/docker-lineage-cicd

Web Site text

The following should be published on the LineageOS for microG website. It is included here until the website can be updated

How do I install the LineageOS for MicroG ROM

Follow the LineageOS installation instructions for your device, which can be accessed from the LineageOS Devices wiki pages. If the LineageOS installation instructions require or refer to any .img files, these images can be obtained by unzipping the -images.zip file mentioned in the previous section.

'Clean' and 'dirty' flashing

A 'clean' flash is when the data partition is wiped and/or formatted before the ROM is installed. This will remove all user-installed apps and data. It is sometimes referred to as a 'fresh installation'.

A 'dirty flash' is when the data partition is not wiped and/or formatted before the ROM is installed. Normally this will result in all user-installed apps and data still being present after the installation.

Newer versions of the LineageOS for MicroG ROM can usually be 'dirty flashed' over older versions with the same Android version.

Dirty flashing is sometimes possible over

In both these cases, problems may be encountered with app permissions, both for user-installed apps and for the pre-installed apps. These problems can sometimes be fixed by manually changing the app permissions.

If you are 'dirty' flashing, it is a good idea to backup your user-installed apps and data in case the 'dirty' flash fails.

Troubleshooting and support

The LineageOS for MicroG project is not in a position to offer much by way of technical support:

The project issue tracker is mostly for tracking problems with the Docker build tool. It is not intended for tracking problems with installing or running the LineageOS for MicroG ROM. If you run into such problems, our advice is to work through the following steps to see if they help. (Make a backup of your user apps & data first):

For any problems, with building, installing, or running LineageOS for MicroG, we recommend that you ask for help in the XDA Forum thread or in device specific XDA forum threads. The LineageOS for MicroG forum thread is not maintained by us, but there are many knowledgeable contributors there, who build and run the LineageOS for MicroG ROM on a wide variety of devices.

Builds for devices no longer supported by LineageOS

When LineageOS stop supporting a device the last LineageOS for MicroG build for that device is moved to a device-specific subdirectory of https://download.lineage.microg.org/archive/

Old builds will be kept here as long as possible, until we need to free up storage space on the download server

LineageOS for microG: Project Scope & Objectives

As the website says, the LineageOS for microG project is a

LineageOS unofficial fork with built-in microG gapps implementation

The prime objectives of the project are to:

Another - less central - objective is to allow other projects and individuals to use our source code and tools (though not currently our computing resources) to make and maintain their own builds:

Upstreams

The project has two main 'upstream` projects:

Like LineageOS, the project also uses 'TheMuppets` github and gitlab repos as the source for device-specific vendor binary blobs.

The main work of the project is to integrate the upstream components and build them into the ROM images we make available.

Project Github repositories

The project has two main public repositories on GitHub:

Project deliverables

  1. The device-specific ROM zip files.
  2. Device-specific -images.zip files containing any .img files that are needed for installing or updating the ROM zip file (e.g. boot.img, recovery.img).
  3. The Docker image used to make the builds, including the (limited) documentation in the README.md.

The ROM zips and other device-specific files are made available in sub-directories on the download server.

The Docker image is pushed to DockerHub.

Build Targets and Frequency

We build for the same devices as LineageOS using their list of build targets as the input to our build run.

We currently make builds monthly, starting on the first day of the month. The devices included in a build run are defined by the content of the LOS target list at the point the build run starts. Our monthly build run takes 15-16 days to complete. You can see the current status of the build in the dedicated matrix room

If builds for any devices fail during a build run, we will try the build again after the main build run has completed. If you do not see a new build for your device when you expect it, please check whether the build failure was reported in the matrix room. If it was, there is no need to report it - we will deal with it! If the failure was not reported in the matrix room, then please report it in our issue tracker or in the XDA Forums thread

Project Scope

The following items are explicitly not within the scope of the project

Project Status

The project is currently in a fairly stable state:

The project is therefore - in the opinion of the currently active maintainers - essentially 'feature complete' and in 'maintenance' mode. The only change that we believe might significantly improve the project is to support other classes of Android devices, specifically

Issue Reporting & Tracking

Our public github repos both have issue trackers, where any github user can create new issues. They are primarily intended for

They are not intended for

One area where we know improvements can be made is in showing the progress (or lack of progress) in addressing reported issues:

Some gradual changes are in hand to address this.

User Support

The project and the currently active maintainers do not have the time or resources to provide 'official' support for users of our ROMs. Fortunately, support and 'self-help' is available from the user community, in particular in the LineageOS for microG' XDA Forums thread.

Upstream projects have their own channels for supporting users.

Notes

  1. If such changes are needed, we will try to provide patches or Pull Requests to the upsteam components. We will only maintain our changes ourselves if the upstreams will not accept our changes
  2. L4M does not currently support building for Minimal or Android TV devices, even when those devices are supported by LOS
  3. This class of problem usually includes device-specific issues: we have no device-specific code, it all comes from upstream
  4. Any new issues or feature requests are more likely to be received positively if they are accompanied by code changes (in patches or - preferred - in Pull Requests) to fix the issue or implement the change. However, such changes will not be accepted just because code changes are provided.