shmayro/dockerify-android repository overview

⁠Dockerify Android

Dockerify Android is a Dockerized Android emulator supporting multiple CPU architectures (x86 and ARM/ARM64 apps via ndk_translation) with native performance and seamless ADB & Web access. It allows developers to run Android virtual devices (AVDs) efficiently within Docker containers, facilitating scalable testing and development environments.

⁠🔥 Key Feature: Web Interface Access 🌐

Access and control the Android emulator directly in your web browser with the integrated scrcpy-web⁠ interface! No additional software needed - just open your browser and start using Android.

⁠🏠 Homepage

⁠📜 Table of Contents

• Features⁠
• Prerequisites⁠
• Installation⁠
• Usage⁠
  • Using Web Interface⁠
  • Using ADB⁠
  • Using Desktop scrcpy⁠
• Environment Variables⁠
• First Boot Process⁠
• Container Logs⁠
• Versioning and Releases⁠
• Roadmap⁠
• Troubleshooting⁠
• Contributing⁠
• License⁠
• Contact⁠

⁠🔧 Features

• 🌐 Web Interface: Access the emulator directly from your browser with the integrated scrcpy-web⁠ interface.
• 🔄 ARM Translation Support: Run ARM/ARM64 native applications on x86_64 emulator using ndk_translation layer. This allows installation of modern Android apps that ship only with ARM native libraries (arm64-v8a, armeabi-v7a).
• Root and Magisk Preinstalled: Comes with root access and Magisk preinstalled for advanced modifications.
• PICO GAPPS Preinstalled: Includes PICO GAPPS for essential Google services.
• Seamless ADB Access: Connect to the emulator via ADB from the host and other networked devices.
• scrcpy Support: Mirror the emulator screen using scrcpy for a seamless user experience.
• Optimized Performance: Utilizes native CPU capabilities for efficient emulation.
• Multi-Architecture Support: Runs natively on both x86 and arm64 CPU architectures.
• Docker Integration: Easily deploy the Android emulator within a Docker container.
• Easy Setup: Simple Docker commands to build and run the emulator.
• Supervisor Management: Manages emulator processes with Supervisor for reliability.
• Unified Container Logs: All emulator and boot logs are redirected to Docker's standard log system.

⁠🛠️ Prerequisites

Before you begin, ensure you have met the following requirements:

• Docker: Installed on your system. Installation Guide⁠
• Docker Compose: For managing multi-container setups. Installation Guide⁠
• KVM Support: Ensure your system supports KVM (Kernel-based Virtual Machine) for hardware acceleration.

  • Check KVM Support:

    egrep -c '(vmx|svm)' /proc/cpuinfo
    

    Copy

    A non-zero output indicates KVM support.

⁠🚀 Installation

To simplify the setup process, you can use the provided docker-compose.yml⁠ file.

1. Clone the Repository:

   git clone https://github.com/shmayro/dockerify-android.git
   cd dockerify-android
   

   Copy

2. Run Docker Compose:

   docker compose up -d
   

   Copy

   Note: This command launches the Android emulator and web interface. First boot takes some time to initialize. Once ready, the device will appear in the web interface at http://localhost:8000⁠.

⁠📡 Usage

⁠🌐 Use the Web Interface to Access the Emulator

The quickest and easiest way to interact with the Android emulator is through your web browser:

1. Open your browser and go to http://localhost:8000
2. You should see the device listed as "dockerify-android:5555" automatically connected
3. Select one of the available streaming options:
   • H264 Converter (recommended for best overall experience)
   • Tiny H264 (good for low-bandwidth connections)
   • Broadway.js (fallback option)

⁠Connect via ADB

If you need direct ADB access to the emulator:

adb connect localhost:5555
adb devices

Expected Output:

connected to localhost:5555
List of devices attached
localhost:5555	device

⁠Use scrcpy to Mirror the Emulator Screen

For a native desktop experience, you can use scrcpy:

scrcpy -s localhost:5555

⁠⚙️ Environment Variables

⁠🔄 First Boot Process

The first time you start the container, it will perform a comprehensive setup process that includes:

1. AVD Creation: Creates a new Android Virtual Device running Android 30 (Android 11)
2. PICO GAPPS Installation (when GAPPS_SETUP=1): Adds essential Google services.
3. Rooting the Device (when ROOT_SETUP=1): Performs multiple reboots to:
   • Disable AVB verification
   • Remount system as writable
   • Install Magisk for root access
   • Reboot to apply root
4. ARM Translation Installation (when ARM_TRANSLATION=1): Installs ndk_translation ARM translation layer to enable running ARM/ARM64 native apps on x86_64:
   • Installs ndk_translation for both ARM32 (armeabi-v7a) and ARM64 (arm64-v8a) support
   • Updates system properties to advertise ARM ABI support
   • Configures native bridge for transparent ARM-to-x86 translation
   • After installation, the device will report ro.product.cpu.abilist = x86_64,x86,arm64-v8a,armeabi-v7a,armeabi
5. Extras Copied: Pushes everything from the extras directory to /sdcard/Download so files like APKs or Magisk modules are ready for manual installation on the device.
6. Configuring optimal device settings

ROOT_SETUP, GAPPS_SETUP, and ARM_TRANSLATION are checked on every start. If you enable them after the first boot, the script installs the requested components once and marks them complete so they won't run again. Removing them later requires recreating the data volume.

After the first boot completes, a file marker is created to prevent running the initialization again on subsequent starts.

⁠📋 Container Logs

All logs from the emulator and boot processes are redirected to Docker's standard log system. To view all container logs:

docker logs -f dockerify-android

This includes:

• Supervisor logs
• Android emulator stdout/stderr
• First-boot process logs

⁠🏷️ Versioning and Releases

Dockerify Android uses GitHub Releases as the source of truth for stable project versions. Publishing a release such as v1.2.3 creates matching Docker image tags: 1.2.3, 1.2, 1, and latest.

Builds from the main branch are published as development images using edge and sha-<short-sha> tags.

⁠🚧 Roadmap

• Support for additional Android versions
• Integration with CI/CD pipelines
• ARM Translation support (ndk_translation) for running ARM64 apps on x86_64
• PICO GAPPS installation
• Support Magisk
• Adding web interface of scrcpy⁠
• Redirect all logs to container stdout/stderr

⁠🐞 Troubleshooting

• ADB Connection Refused:

  • Ensure ADB Server is Running:

    adb start-server -a
    

    Copy

  • Verify Firewall Settings: Ensure that port 5555 is open on your server.

  • Check Emulator Status: Ensure the emulator has fully booted by checking logs.

    docker logs dockerify-android
    

    Copy

• First Boot Taking Too Long:

  • This is normal, as the first boot process needs to perform several operations including:
    • Installing GAPPS (if enabled)
    • Rooting the device (if enabled)
    • Installing ARM Translation (if enabled)
    • Configuring system settings
  • The process can take 10-15 minutes depending on your system performance
  • You can monitor progress with docker logs -f dockerify-android

• ARM/ARM64 Apps Still Not Installing:

  • Ensure ARM_TRANSLATION=1 is set in your docker-compose.yml or environment variables
  • Check that the first boot completed successfully with docker logs dockerify-android | grep -i "ARM translation"
  • Verify ARM ABIs are available:

    adb shell getprop ro.product.cpu.abilist
    

    Copy
    Should show: x86_64,x86,arm64-v8a,armeabi-v7a,armeabi
  • If you enabled ARM_TRANSLATION after the first boot, restart the container to run the install step

• Emulator Not Starting:

  • Check Container Logs:

    docker logs dockerify-android
    

    Copy

• KVM Not Accessible:

  • Verify KVM Installation:

    lsmod | grep kvm
    

    Copy

  • Check Permissions: Ensure your user has access to /dev/kvm.

⁠🤝 Contributing

Contributions are welcome! To contribute:

1. Fork the Repository

2. Create a Feature Branch:

   git checkout -b feature/YourFeature
   

   Copy

3. Commit Your Changes:

   git commit -m "Add Your Feature"
   

   Copy

4. Push to the Branch:

   git push origin feature/YourFeature
   

   Copy

5. Open a Pull Request

Please ensure your contributions adhere to the project's coding standards and include relevant tests.

⁠📄 License

This project is licensed under the MIT License⁠.

⁠📫 Contact

• Haroun EL ALAMI
• Email: [email protected]⁠
• GitHub: shmayro⁠
• Twitter: @HarounDev⁠