DEV Community

Cover image for docker-android: A Docker Environment for Controlling Android Emulators from a Web Browser
tumf
tumf

Posted on • Originally published at blog.tumf.dev

docker-android: A Docker Environment for Controlling Android Emulators from a Web Browser

#docker #devops #testing

Originally published on 2026-01-04
Original article (Japanese): docker-android: WebブラウザからAndroidエミュレータを操作するDocker環境

docker-android is an open-source project that allows you to run Android emulators inside a Docker container and control them remotely via a web browser. This enables the automation of testing in CI/CD pipelines and the creation of a scalable Android testing infrastructure in cloud environments without the need to install Android Studio.

In this article, we will cover an overview of docker-android, how to set it up, basic usage, and practical use cases.

What is docker-android?

docker-android is a Docker-based Android emulator environment developed by budtmo. Its main features are as follows:

Key Features

  • Web Browser Access: Directly control the Android screen from the browser using noVNC.
  • Multiple Version Support: Supports Android versions from 5.0 to the latest.
  • CI/CD Integration: Easily integrates with Jenkins, GitLab CI, GitHub Actions, and more.
  • Appium Support: Can be integrated with test automation frameworks.
  • Scalability: Supports scale-out with Kubernetes or Docker Swarm.

Architecture

docker-android consists of the following components.

graph TB
    Browser[Webブラウザ]
    noVNC[noVNC Server<br/>Port: 6080]
    VNC[VNC Server]
    Emulator[Android Emulator<br/>AVD]
    Appium[Appium Server<br/>Port: 4723<br/>オプション]
    ADB[ADB Server<br/>Port: 5554/5555]

    Browser -->|HTTP| noVNC
    noVNC -->|VNC Protocol| VNC
    VNC --> Emulator
    Appium --> ADB
    ADB --> Emulator

    style Browser fill:#e1f5ff
    style Emulator fill:#a5d6a7
    style noVNC fill:#fff59d
    style Appium fill:#ffcc80
Enter fullscreen mode Exit fullscreen mode

Main components:

  • Android Emulator: Android SDK's AVD (Android Virtual Device)
  • noVNC: A web interface that allows VNC to be accessed from a browser.
  • Appium Server: A WebDriver server for test automation (optional).
  • ADB (Android Debug Bridge): For debugging and command execution.

Setup

Prerequisites

  • Docker: Version 20.10 or higher.
  • Hardware Virtualization: Intel VT-x or AMD-V must be enabled.
  • Memory: Minimum of 4GB (8GB or more recommended).

Basic Startup Method

The simplest way to start an Android 11 emulator is with the following command.

docker run -d -p 6080:6080 -p 5554:5554 -p 5555:5555 \
  --name android-container \
  budtmo/docker-android:emulator_11.0
Enter fullscreen mode Exit fullscreen mode

After starting, accessing http://localhost:6080 in your browser will display the Android screen.

Port Descriptions

Port Purpose
6080 noVNC (Web Interface)
5554 ADB Console Port
5555 ADB Debug Port
4723 Appium Server (when using Appium image)

Basic Usage

Operating from a Web Browser

  1. Access http://localhost:6080 in your browser.
  2. Click, drag, and swipe on the screen to control Android.
  3. Keyboard input is also possible.

Operating via ADB

You can access the Android inside the container from the Docker host using ADB.

# ADB connection
adb connect localhost:5555

# Check device list
adb devices

# Install an app
adb install my-app.apk

# Shell access
adb shell
Enter fullscreen mode Exit fullscreen mode

Configuration with Docker Compose

If you want to start multiple emulators, using Docker Compose is convenient.

version: '3'
services:
  android-11:
    image: budtmo/docker-android:emulator_11.0
    ports:
      - "6080:6080"
      - "5554:5554"
      - "5555:5555"
    environment:
      - DEVICE=Samsung Galaxy S10
      - DATAPARTITION=4g
    privileged: true

  android-13:
    image: budtmo/docker-android:emulator_13.0
    ports:
      - "6081:6080"
      - "5556:5554"
      - "5557:5555"
    environment:
      - DEVICE=Pixel 6
      - DATAPARTITION=4g
    privileged: true
Enter fullscreen mode Exit fullscreen mode

Startup command:

docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

This will start two emulators, Android 11 and Android 13, accessible on different ports.

Test Automation with Appium

docker-android also provides an image with an integrated Appium server. Appium is an open-source framework for automating mobile application testing.

Starting the Appium Image 

docker run -d -p 6080:6080 -p 4723:4723 -p 5555:5555 \
  --name appium-android \
  budtmo/docker-android:emulator_11.0_appium
Enter fullscreen mode Exit fullscreen mode

Example Test Code in Python + Appium

Here is an example of Python code to test an Android app using Appium.

from appium import webdriver
from appium.options.android import UiAutomator2Options

# Appium server configuration
options = UiAutomator2Options()
options.platform_name = 'Android'
options.platform_version = '11'
options.device_name = 'emulator-5554'
options.app = '/path/to/your/app.apk'

# Connect to Appium server
driver = webdriver.Remote('http://localhost:4723', options=options)

# Example test execution
try:
    # Get element and click
    element = driver.find_element('id', 'com.example:id/button')
    element.click()

    # Text input
    input_field = driver.find_element('id', 'com.example:id/input')
    input_field.send_keys('Hello, docker-android!')

    print("Test successful")
finally:
    driver.quit()
Enter fullscreen mode Exit fullscreen mode

Example of Using in CI/CD Pipeline (GitHub Actions)

Here’s an example of running tests using docker-android in GitHub Actions.

name: Android UI Tests

on:
  push:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Start Android emulator
        run: |
          docker run -d -p 4723:4723 -p 5555:5555 \
            --name android-emulator \
            budtmo/docker-android:emulator_11.0_appium

          # Wait for the emulator to start
          sleep 30

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install appium-python-client pytest

      - name: Run tests
        run: |
          pytest tests/test_android.py

      - name: Stop emulator
        if: always()
        run: docker stop android-emulator
Enter fullscreen mode Exit fullscreen mode

Customization via Environment Variables

docker-android allows you to customize the emulator's behavior using the following environment variables.

Environment Variable Description Default Value
DEVICE Device model name Samsung Galaxy S10
DATAPARTITION Data partition size 2g
EMULATOR_TIMEOUT Startup timeout (seconds) 300
RELAXED_SECURITY Relax security for Appium false

Usage example:

docker run -d -p 6080:6080 -p 5555:5555 \
  -e DEVICE="Pixel 6" \
  -e DATAPARTITION="4g" \
  budtmo/docker-android:emulator_13.0
Enter fullscreen mode Exit fullscreen mode

Utilizing in Cloud Environments

Example Configuration on AWS ECS

docker-android can also run in container orchestration environments like AWS ECS and GCP Cloud Run.

Here is an example of an AWS ECS task definition (excerpt).

{
  "family": "android-emulator-task",
  "containerDefinitions": [
    {
      "name": "android-emulator",
      "image": "budtmo/docker-android:emulator_11.0_appium",
      "memory": 4096,
      "cpu": 2048,
      "essential": true,
      "portMappings": [
        {
          "containerPort": 6080,
          "protocol": "tcp"
        },
        {
          "containerPort": 4723,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {
          "name": "DEVICE",
          "value": "Samsung Galaxy S10"
        },
        {
          "name": "DATAPARTITION",
          "value": "4g"
        }
      ]
    }
  ],
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "2048",
  "memory": "4096"
}
Enter fullscreen mode Exit fullscreen mode

Example Configuration on Kubernetes

Example of a Deployment in Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: android-emulator
spec:
  replicas: 3
  selector:
    matchLabels:
      app: android-emulator
  template:
    metadata:
      labels:
        app: android-emulator
    spec:
      containers:
      - name: android
        image: budtmo/docker-android:emulator_11.0_appium
        ports:
        - containerPort: 6080
        - containerPort: 4723
        resources:
          limits:
            memory: "4Gi"
            cpu: "2"
          requests:
            memory: "2Gi"
            cpu: "1"
        env:
        - name: DEVICE
          value: "Pixel 6"
        - name: DATAPARTITION
          value: "4g"
---
apiVersion: v1
kind: Service
metadata:
  name: android-emulator-service
spec:
  selector:
    app: android-emulator
  ports:
  - name: novnc
    port: 6080
    targetPort: 6080
  - name: appium
    port: 4723
    targetPort: 4723
  type: LoadBalancer
Enter fullscreen mode Exit fullscreen mode

Performance and Resource Management

Resource Requirements

Recommended resources per emulator:

  • CPU: 2 cores or more
  • Memory: 4GB or more (8GB recommended for Android 11 and later)
  • Disk: 10GB or more

Considerations for Parallel Execution

When starting multiple emulators simultaneously, keep the following points in mind:

  • Avoid port number conflicts.
  • Properly allocate resources on the host machine.
  • Set resource limits using Docker's --cpus and --memory options.

Example of parallel execution:

# Emulator 1
docker run -d -p 6080:6080 -p 5555:5555 \
  --cpus="2" --memory="4g" \
  --name android-1 \
  budtmo/docker-android:emulator_11.0

# Emulator 2
docker run -d -p 6081:6080 -p 5556:5555 \
  --cpus="2" --memory="4g" \
  --name android-2 \
  budtmo/docker-android:emulator_11.0
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

If the Emulator Fails to Start

Cause: Hardware virtualization is disabled.

Solution: Enable Intel VT-x or AMD-V in the BIOS. For Linux, check if KVM is available.

# Check if KVM is available
egrep -c '(vmx|svm)' /proc/cpuinfo
Enter fullscreen mode Exit fullscreen mode

If noVNC Cannot Connect

Cause: Port mapping is incorrect.

Solution: Verify that the ports are correctly mapped with the -p option.

# Check port usage
docker port android-container
Enter fullscreen mode Exit fullscreen mode

Memory Insufficient Error

Cause: Insufficient memory allocated to the container.

Solution: Increase memory with the --memory option or reduce the DATAPARTITION environment variable.

docker run -d -p 6080:6080 -p 5555:5555 \
  --memory="8g" \
  -e DATAPARTITION="2g" \
  budtmo/docker-android:emulator_11.0
Enter fullscreen mode Exit fullscreen mode

Comparison with Android Studio Emulator

Item docker-android Android Studio Emulator
Ease of Setup ◎ (Only Docker) △ (Requires Android Studio)
CI/CD Integration ◎ (Easy) △ (Complex setup)
Remote Access ◎ (Via browser) × (Requires VNC, etc.)
Performance ○ (Slightly slower) ◎ (Native-like performance)
Scalability ◎ (Containerized) △ (Manual management)
GPU Support △ (Limited support*) ◎ (Full support)
  • GPU passthrough configuration is required in container environments.

While docker-android is suitable for automated testing in CI/CD and cloud environments, the Android Studio Emulator performs better for local development.

Conclusion

Using docker-android significantly simplifies the setup of Android emulator environments, making it easy to automate testing in CI/CD pipelines and build scalable testing infrastructures in cloud environments.

Key benefits include:

  • No need for Android Studio, allowing control of Android from a browser.
  • High reproducibility of environments as it can be managed as a Docker container.
  • Powerful test automation can be achieved in combination with Appium.
  • Scalable with Kubernetes or ECS.

If you are considering automated testing in CI/CD or building an Android testing infrastructure in cloud environments, be sure to give it a try.

Related Articles

Reference Links

Top comments (0)