paulgl721/mobile_build_environment repository overview

⁠Android Build Environment

Spend less time configuring build agents and more time building Android apps.

Managing Android SDKs, Java, and Gradle across automated builds can be time-consuming. This repository provides Docker build images for different Android API levels, with the tools already installed. Choose the image that matches your project and use it locally, in Jenkins, or in any CICD tool. Build older projects and newer applications without repeatedly reconfiguring your build machine.

Included: Android SDK, build tools, Java, Gradle, Node.js, npm, Cordova CLI, and Git.

⁠Choose an image

Choose a tag matching your project's compile SDK and Java requirements.

Published example for API 34 (Android 14):

paulgl721/mobile_build_environment:cordovaAPI34-V1.2.99

• cordovaAPI34 means Android API 34.
• V1.2.99 is the image's build version.

Other tags follow the same pattern:

paulgl721/mobile_build_environment:cordovaAPI<API>-V<VERSION>

Browse the Tags tab⁠ for available versions.

⁠Quick start

Start Docker and open a macOS or Linux terminal. Choose the section for your project:

Both examples use the published API 34 image. Choose a different Docker Hub tag⁠ if your project requires another Android SDK or Java version.

⁠Build a native Android app

Start in a native Android project containing gradlew, the Gradle Wrapper script normally created by Android Studio. You do not install this script separately.

Replace the path below with your project folder, then run:

cd /path/to/your/android-app
export IMAGE="paulgl721/mobile_build_environment:cordovaAPI34-V1.2.99"
docker pull --platform linux/amd64 "$IMAGE"
docker volume create android-gradle-cache
# Initialize ownership so the build can use your user ID.
docker run --rm --platform linux/amd64 --user 0:0 \
  -v android-gradle-cache:/gradle-cache \
  "$IMAGE" chown "$(id -u):$(id -g)" /gradle-cache

docker run --rm --platform linux/amd64 \
  --user "$(id -u):$(id -g)" \
  -e HOME=/workspace \
  -e GRADLE_USER_HOME=/gradle-cache \
  -e ANDROID_USER_HOME=/workspace/.android \
  -v android-gradle-cache:/gradle-cache \
  -v "$PWD:/workspace" -w /workspace \
  "$IMAGE" bash ./gradlew --no-daemon assembleDebug

The volume stores Gradle downloads and caches across builds. Creating it again reuses the existing volume; --rm removes the container but keeps the volume.

Find your APK: typically app/build/outputs/apk/debug/ in your project folder.

⁠Build a Cordova app

Prerequisite: install the Android platform in your Cordova project before running cordova build android. The Docker image includes the Android SDK and Cordova CLI, but your project also needs its own compatible cordova-android platform.

Use this section for an existing Cordova project with its dependencies installed. You do not need gradlew in your Cordova root folder or a separate local installation of Java, Gradle, or the Android SDK.

Replace the path below with the folder containing config.xml and package.json:

cd /path/to/your/cordova-app
export IMAGE="paulgl721/mobile_build_environment:cordovaAPI34-V1.2.99"
docker pull --platform linux/amd64 "$IMAGE"
docker volume create android-gradle-cache
# Initialize ownership so the build can use your user ID.
docker run --rm --platform linux/amd64 --user 0:0 \
  -v android-gradle-cache:/gradle-cache \
  "$IMAGE" chown "$(id -u):$(id -g)" /gradle-cache

docker run --rm --platform linux/amd64 \
  --user "$(id -u):$(id -g)" \
  -e HOME=/workspace \
  -e GRADLE_USER_HOME=/gradle-cache \
  -e ANDROID_USER_HOME=/workspace/.android \
  -e npm_config_cache=/workspace/.npm \
  -v android-gradle-cache:/gradle-cache \
  -v "$PWD:/workspace" -w /workspace \
  "$IMAGE" cordova build android

Before the build, check the installed platforms. After setting IMAGE and pulling it as shown above, run this from the same Cordova project folder:

docker run --rm --platform linux/amd64 \
  --user "$(id -u):$(id -g)" \
  -e HOME=/workspace \
  -e npm_config_cache=/workspace/.npm \
  -v "$PWD:/workspace" -w /workspace \
  "$IMAGE" cordova platform ls

If Android is missing, install it first using the same container options:

docker run --rm --platform linux/amd64 \
  --user "$(id -u):$(id -g)" \
  -e HOME=/workspace \
  -e npm_config_cache=/workspace/.npm \
  -v "$PWD:/workspace" -w /workspace \
  "$IMAGE" cordova platform add [email protected]

This example pins Cordova Android 13.0.0, which uses API 34⁠. For another image, choose a cordova-android version compatible with your project's plugins and the image's SDK and Java versions. If Android is already installed, keep your project's compatible version. The platform is saved in your mounted project; then run the cordova build android command above.

Find your APK: typically platforms/android/app/build/outputs/apk/debug/app-debug.apk in your project folder.

-v "$PWD:/workspace" connects your current project folder to the container. -w /workspace runs the build there. Your files and APK stay on your computer; Docker removes the temporary container when the build finishes.

⁠Gradle extraction fails with an input/output error on macOS

If Gradle downloads successfully but fails to unzip under /workspace/.gradle, the error is a filesystem write failure. Check free space on your Mac and Docker Desktop's disk usage. The log alone does not establish the cause.

The quick-start commands above use a Docker volume for Gradle's cache, keeping it inside Docker's Linux VM instead of the Mac project mount. If you previously used /workspace/.gradle, switch to the volume with the commands below. Docker recommends volumes for cache directories in its Docker Desktop settings guide⁠. From your application folder, with IMAGE set to a compatible image, run:

docker volume create android-gradle-cache
# Initialize ownership so the build can use your user ID.
docker run --rm --platform linux/amd64 --user 0:0 \
  -v android-gradle-cache:/gradle-cache \
  "$IMAGE" chown "$(id -u):$(id -g)" /gradle-cache

docker run --rm --platform linux/amd64 \
  --user "$(id -u):$(id -g)" \
  -e HOME=/workspace \
  -e GRADLE_USER_HOME=/gradle-cache \
  -e ANDROID_USER_HOME=/workspace/.android \
  -e npm_config_cache=/workspace/.npm \
  -v android-gradle-cache:/gradle-cache \
  -v "$PWD:/workspace" -w /workspace \
  "$IMAGE" cordova build android

This leaves the old .gradle cache untouched and downloads Gradle again into the volume. For native Android, replace cordova build android with bash ./gradlew --no-daemon assembleDebug. If the error continues, inspect Docker Desktop's available disk space and restart Docker Desktop before retrying.

Also check cordova platform ls: the project's Gradle wrapper can use a different version from the Gradle bundled in the image. For example, Cordova Android 15⁠ uses Gradle 8.14.2 and SDK/build-tools 36; its default requirements do not match the API 34 image. Choose a matching image or a platform version compatible with API 34 before building.

⁠Jenkins and compatibility

Use a published image tag as a Jenkins Docker agent. Your worker needs Docker and the Docker Pipeline plugin.

• Images target Linux AMD64; ARM hosts require emulation.
• The image does not change your project's SDK settings or dependencies.
• Match your project's Gradle, Android Gradle plugin, and Cordova Android versions to the image's tools.
• These images do not include an emulator. Additional SDK packages may require a custom image.
• Keep signing keys and passwords outside images and source control.

Source, version details, and Jenkins examples⁠