# hqarroum/docker-android architecture

> Architecture diagram of the GitHub repository hqarroum/docker-android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hqarroum/docker-android
- Repository: https://github.com/hqarroum/docker-android

## Overview

1. **What this repository produces**
   - This repo builds a **Docker image that runs the Android Emulator as a headless service**.
   - The container is intended for **CI, automated testing, and remote control** rather than interactive desktop use.

2. **Core runtime boundary**
   - The main runtime boundary is the **container vs. host**.
   - The host must provide **KVM hardware acceleration** via `/dev/kvm`, and the container exposes the emulator/ADB network ports so external tools can connect.
   - The emulator itself runs inside the container; control happens from outside through **ADB**, and optionally through tools like **scrcpy**.

3. **Image composition**
   - The image is based on **Alpine Linux** and includes the Android emulator stack plus **JRE 11**.
   - The build can include or omit the **Android SDK / emulator components**, which materially changes image size and build time.
   - The repo supports building a minimal runtime image or a larger pre-bundled variant.

4. **Build-time configuration subsystem**
   - Image contents are parameterized by build args such as **API_LEVEL**, **IMG_TYPE**, **ARCHITECTURE**, and **INSTALL_ANDROID_SDK**.
   - These determine:
     - Android version
     - Image flavor, such as **Google APIs** vs **Play Store**
     - CPU architecture, mainly **x86_64** and **x86**
     - Whether SDK installation is baked into the image
   - This is the main mechanism for producing multiple emulator variants from one repository.

5. **Container startup flow**
   - At runtime, the container starts the emulator, then brings up an **ADB server** bound inside the container.
   - The emulator is configured to run **headless**, with defaults tuned for automation: fixed memory, CPU cores, and extra emulator flags.
   - The startup scripts in `scripts/` likely split responsibilities between **SDK installation**, **emulator launch**, and **monitoring/recovery**.

6. **Persistence and wipe behavior**
   - Emulator state is stored under **`/data`** in the container.
   - If no volume is mounted, emulator storage is effectively ephemeral and gets wiped on restart.
   - If a host volume is mounted to `/data`, the AVD state can persist across container runs.
   - This creates a clear separation between disposable runtime state and persistent device images.

7. **ADB and remote control path**
   - External clients connect to the container’s **ADB port 5555**.
   - Once connected, the Android device inside the emulator becomes available for automation, testing, and optional screen control.
   - The README explicitly positions **scrcpy** as a supported remote-control path that rides on top of the ADB connection.

8. **GPU and variant support**
   - The repo includes a separate **`Dockerfile.gpu`** and compose targets for GPU-accelerated variants.
   - That indicates two runtime modes: **software/headless emulation** and **accelerated emulation** using host GPU capabilities where available.
   - The compose file acts as the main orchestration layer for choosing between variants like standard, CUDA, and Play Store images.

9. **Key management boundary for Play Store images**
   - Play Store-based emulator images require matching **ADB keys** between the emulator container and the client.
   - The `keys/` directory contains default `adbkey` / `adbkey.pub`, and the README documents overriding them.
   - This is an authentication boundary that matters only for certain image flavors, especially Play Store builds.

10. **Operational scripts**
    - `install_android.sh` and the scripts under `scripts/` are the operational glue for fetching SDK content, starting the emulator, and supervising it.
    - `emulator-monitoring.sh` suggests the container includes a lightweight process-management layer to keep the emulator usable in unattended environments.
    - These scripts are the main internal implementation surface, while Docker and Compose define the deployment surface.

11. **CI/CD and release flow**
    - GitHub Actions workflows build and publish Docker images, likely for multiple image variants.
    - The repo also contains `.travis.yml`, showing legacy or secondary CI support.
    - The resulting artifacts are published to **Docker Hub**, where tags correspond to emulator API levels and image flavors.

12. **Primary external dependencies**
    - The architecture depends on:
      - **Android SDK / emulator distributions** for the guest runtime
      - **KVM** on the host for performance
      - **Docker** for packaging and execution
      - Optional **GPU drivers/CUDA** for accelerated variants
    - These dependencies are central to the design; the repo is essentially a packaging and orchestration layer around them.

13. **How to diagram it**
    - A good architecture diagram would show:
      - **Build inputs**: Dockerfiles, scripts, build args, keys
      - **Build pipeline**: GitHub Actions producing tagged images
      - **Runtime container**: Android emulator + ADB server + optional SDK
      - **Host interfaces**: `/dev/kvm`, mounted `/data`, exposed port 5555, optional GPU
      - **External clients**: adb, scrcpy, CI jobs, and test runners connecting over ADB

Main entry points: [`Dockerfile`](https://github.com/hqarroum/docker-android/tree/main/Dockerfile) (Dockerfile), [`scripts/start-emulator.sh`](https://github.com/hqarroum/docker-android/blob/main/scripts/start-emulator.sh) (Start emulator), [`Dockerfile.gpu`](https://github.com/hqarroum/docker-android/blob/main/Dockerfile.gpu) (GPU Dockerfile), [`docker-compose.yml`](https://github.com/hqarroum/docker-android/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & release"]
  node_dockerfile["Dockerfile<br/>image build"]
  node_dockerfile_gpu["GPU Dockerfile<br/>image build<br/>[Dockerfile.gpu]"]
  node_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
  node_build_args{{"Build args<br/>config knobs"}}
  node_install_android["Android install<br/>bootstrap<br/>[install_android.sh]"]
  node_github_actions["GitHub Actions<br/>release CI<br/>[docker-image.yml]"]
  node_travis["Travis CI<br/>legacy CI<br/>[.travis.yml]"]
end

subgraph group_runtime["Container runtime"]
  node_alpine_base["Alpine base<br/>linux base"]
  node_android_sdk["Android SDK<br/>guest stack<br/>[install-sdk.sh]"]
  node_start_emulator(("Start emulator<br/>runtime entrypoint<br/>[start-emulator.sh]"))
  node_monitoring["Monitoring<br/>supervision"]
  node_data_state[("AVD state<br/>persistent state")]
end

subgraph group_ops["Host & clients"]
  node_host_kvm["KVM<br/>host accel"]
  node_host_gpu["GPU drivers<br/>host accel"]
  node_adb_clients(("ADB clients<br/>external tools"))
  node_scrcpy(("scrcpy<br/>remote control"))
  node_adb_keys["ADB keys<br/>auth material"]
  node_dockerhub[("Docker Hub<br/>image registry")]
end

node_dockerfile -->|"builds on"| node_alpine_base
node_dockerfile_gpu -->|"builds on"| node_alpine_base
node_dockerfile -->|"parameterized by"| node_build_args
node_dockerfile_gpu -->|"parameterized by"| node_build_args
node_install_android -->|"installs"| node_android_sdk
node_dockerfile -->|"includes"| node_android_sdk
node_compose -->|"runs"| node_dockerfile
node_compose -->|"runs"| node_dockerfile_gpu
node_compose -->|"starts"| node_start_emulator
node_start_emulator -->|"uses"| node_monitoring
node_monitoring -->|"supervises"| node_start_emulator
node_start_emulator -->|"persists state"| node_data_state
node_host_kvm -->|"accelerates"| node_start_emulator
node_host_gpu -->|"enables"| node_dockerfile_gpu
node_adb_clients -->|"connects to"| node_start_emulator
node_scrcpy -->|"uses"| node_start_emulator
node_adb_keys -->|"supports"| node_dockerfile
node_adb_keys -->|"trusted by"| node_adb_clients
node_github_actions -->|"builds"| node_dockerfile
node_github_actions -->|"builds"| node_dockerfile_gpu
node_github_actions -->|"publishes"| node_dockerhub
node_travis -.->|"validates"| node_dockerfile

click node_dockerfile "https://github.com/hqarroum/docker-android/tree/main/Dockerfile"
click node_dockerfile_gpu "https://github.com/hqarroum/docker-android/blob/main/Dockerfile.gpu"
click node_compose "https://github.com/hqarroum/docker-android/blob/main/docker-compose.yml"
click node_install_android "https://github.com/hqarroum/docker-android/blob/main/install_android.sh"
click node_github_actions "https://github.com/hqarroum/docker-android/blob/main/.github/workflows/docker-image.yml"
click node_travis "https://github.com/hqarroum/docker-android/blob/main/.travis.yml"
click node_android_sdk "https://github.com/hqarroum/docker-android/blob/main/scripts/install-sdk.sh"
click node_start_emulator "https://github.com/hqarroum/docker-android/blob/main/scripts/start-emulator.sh"
click node_monitoring "https://github.com/hqarroum/docker-android/blob/main/scripts/emulator-monitoring.sh"
click node_adb_keys "https://github.com/hqarroum/docker-android/tree/main/keys/adbkey"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dockerfile,node_dockerfile_gpu,node_compose,node_build_args,node_install_android,node_github_actions,node_travis toneBlue
class node_alpine_base,node_android_sdk,node_start_emulator,node_monitoring,node_data_state toneAmber
class node_host_kvm,node_host_gpu,node_adb_clients,node_scrcpy,node_adb_keys,node_dockerhub toneMint
```

## Components

### Build & release

Image definitions, build-time parameters, and publishing workflows.

- [Dockerfile](https://github.com/hqarroum/docker-android/tree/main/Dockerfile): image build · Main image definition for the standard headless emulator runtime. · `Dockerfile`
- [GPU Dockerfile](https://github.com/hqarroum/docker-android/blob/main/Dockerfile.gpu): image build · Alternative image definition for accelerated emulator runs. · `Dockerfile.gpu`
- [Compose](https://github.com/hqarroum/docker-android/blob/main/docker-compose.yml): orchestration · Local deployment entrypoint for selecting image variants and runtime settings. · `docker-compose.yml`
- **Build args**: config knobs · API level, image type, architecture, and SDK-install toggles.
- [Android install](https://github.com/hqarroum/docker-android/blob/main/install_android.sh): bootstrap · Top-level installer for fetching and preparing Android components. · `install_android.sh`
- [GitHub Actions](https://github.com/hqarroum/docker-android/blob/main/.github/workflows/docker-image.yml): release CI · Workflows that build and publish tagged Docker image variants. · `.github/workflows/docker-image.yml`
- [Travis CI](https://github.com/hqarroum/docker-android/blob/main/.travis.yml): legacy CI · Secondary CI configuration for validating builds. · `.travis.yml`

### Container runtime

Emulator process, startup scripts, and in-container state management.

- **Alpine base**: linux base · Lean Linux foundation for the container image.
- [Android SDK](https://github.com/hqarroum/docker-android/blob/main/scripts/install-sdk.sh): guest stack · Optional bundled SDK and emulator components baked into the image. · `scripts/install-sdk.sh`
- [Start emulator](https://github.com/hqarroum/docker-android/blob/main/scripts/start-emulator.sh): runtime entrypoint · Launches the headless emulator and brings up ADB. · `scripts/start-emulator.sh`
- [Monitoring](https://github.com/hqarroum/docker-android/blob/main/scripts/emulator-monitoring.sh): supervision · Lightweight recovery and process supervision for unattended runs. · `scripts/emulator-monitoring.sh`
- **AVD state**: persistent state · Emulator data stored under /data; persists only when mounted from the host.

### Host & clients

Host acceleration, external automation, and authentication boundaries.

- **KVM**: host accel · Hardware virtualization exposed to the container through /dev/kvm.
- **GPU drivers**: host accel · Optional GPU/CUDA acceleration path for accelerated variants.
- **ADB clients**: external tools · CI jobs, test runners, and automation tools connecting over ADB.
- **scrcpy**: remote control · Optional screen/control client layered on top of ADB.
- [ADB keys](https://github.com/hqarroum/docker-android/tree/main/keys/adbkey): auth material · Keypair used for Play Store-compatible image authentication. · `keys/adbkey`
- **Docker Hub**: image registry · Published destination for tagged emulator image artifacts.

## Connections

- Dockerfile → Alpine base: builds on · Standard image starts from Alpine Linux.
- GPU Dockerfile → Alpine base: builds on · GPU variant also uses the Alpine base.
- Dockerfile → Build args: parameterized by · Build args control emulator flavor, CPU architecture, and SDK inclusion.
- GPU Dockerfile → Build args: parameterized by · Accelerated variant also depends on build-time configuration.
- Android install → Android SDK: installs · Bootstrap script fetches and prepares Android tooling.
- Dockerfile → Android SDK: includes · SDK content is baked into the image when enabled.
- Compose → Dockerfile: runs · Compose can launch the standard image path.
- Compose → GPU Dockerfile: runs · Compose can select the accelerated variant.
- Compose → Start emulator: starts · Container startup path launches the emulator and ADB server.
- Start emulator → Monitoring: uses · Startup flow relies on monitoring for unattended operation.
- Monitoring → Start emulator: supervises · Monitoring keeps the emulator usable during long runs.
- Start emulator → AVD state: persists state · Emulator state is stored under /data and can survive restarts when mounted.
- KVM → Start emulator: accelerates · Host KVM acceleration improves emulator performance.
- GPU drivers → GPU Dockerfile: enables · GPU variant relies on host graphics acceleration.
- ADB clients → Start emulator: connects to · External automation reaches the device through ADB.
- scrcpy → Start emulator: uses · Remote control rides on top of the ADB connection.
- ADB keys → Dockerfile: supports · Key material is used for Play Store-compatible images.
- ADB keys → ADB clients: trusted by · Certain variants require matching client and container keys.
- GitHub Actions → Dockerfile: builds · CI builds and publishes standard image variants.
- GitHub Actions → GPU Dockerfile: builds · CI also builds GPU-enabled variants.
- GitHub Actions → Docker Hub: publishes · Built images are pushed as tagged artifacts.
- Travis CI → Dockerfile: validates · Legacy CI can still exercise the main build.