The Problem
CI pipelines and automated test environments often need a reproducible Android device, but provisioning physical hardware or full‑featured emulators is slow, heavyweight, and hard to scale. Teams that run headless builds lack a lightweight, disposable Android target that can be started on demand inside containers.
What This Does
docker-android supplies a minimal Alpine‑based Docker image that runs the Android emulator as a background service. The core build logic lives in Dockerfile (standard image) and Dockerfile.gpu (CUDA‑enabled variant). The image bundles the Android SDK, platform‑tools, and a JRE 11 runtime, exposing ADB on port 5555 and forwarding the emulator’s display via scrcpy‑compatible networking.
Key scripts in scripts/ orchestrate the container lifecycle:
scripts/install-sdk.sh – downloads the requested SDK components based on the ANDROIDSDKROOT arguments defined in the Dockerfile. scripts/start-emulator.sh – launches the emulator with headless flags, sets up ADB, and writes the AVD under /data. scripts/emulator-monitoring.sh – watches the QEMU process and ensures the container exits cleanly on failure.
Configuration is driven by build‑time arguments (e.g., ANDROIDAPI, ANDROIDABI, DEVICE) that can be overridden in docker-compose.yml. The keys/ directory holds an ADB key pair (adbkey, adbkey.pub) required when using Google Play images.
How To Use It
Setup – Build the image (or let Docker Compose handle it):
Build locally
docker build -t android-emulator .
Or use the provided compose file
docker compose up android-emulator # CPU only docker compose up android-emulator-cuda # GPU acceleration
Configuration – Adjust the compose file or pass build args:
example snippet from docker-compose.yml services: android-emulator: build: context: . args: ANDROIDAPI: 33 DEVICE: pixel IMAGETYPE: googleapis devices: /dev/kvm:/dev/kvm ports: "5555:5555" volumes: ~/androidavd:/data # persist AVD across restarts
For Play Store images, replace the default keys with a matching pair generated by adb keygen adbkey and place the two files in keys/.
Running – Start the container, then connect from the host:
docker run -it --rm --device /dev/kvm -p 5555:5555 -v ~/android_avd:/data android-emulator adb connect 127.0.0.1:5555 scrcpy # optional UI control
The emulator boots headlessly; after a few seconds adb devices will list the remote device.
Real‑World Use
A CI job can spin up the container, run UI tests with Espresso, and tear it down automatically:
steps: name: Start Android emulator run: docker compose up -d android-emulator name: Run UI tests run: ./gradlew connectedAndroidTest name: Stop emulator run: docker compose down
Because the AVD is stored under /data, mounting a host volume preserves state between runs, enabling incremental builds or debugging sessions.
Code Health & Issues
Medium – No test suite – Repository contains no unit or integration tests; emulator launch scripts (start-emulator.sh, install-sdk.sh) are exercised only by CI image builds. Low – Hard‑coded paths – Scripts assume /data and /opt/android-sdk exist; missing sanity checks could cause failures on custom mounts. Medium – Limited error handling – scripts/emulator-monitoring.sh exits on QEMU failure but does not surface detailed logs, making troubleshooting harder. Low – Secrets handling – ADB keys are stored unencrypted in keys/; while intended for local use, production pipelines should treat them as secrets. Info – CI configured – .github/workflows/docker-image.yml and .travis.yml build and push images, providing basic CI coverage for build integrity. Info – License present – LICENSE file grants Apache‑2.0, meeting open‑source compliance.
The Bottom Line
docker-android delivers a functional, lightweight Android emulator container suitable for CI/CD and automated testing, with clear build and runtime scripts. It lacks automated tests and could improve robustness around error handling and secret management. Teams needing repeatable Android environments in Docker will find it immediately useful; larger enterprises should augment it with their own test coverage and secret controls.