Repository files navigation

Dockerify Android is a Dockerized Android emulator supporting multiple CPU architectures (x86 andarm64 in the near future ...) 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.

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

Benefits of Web Interface:

• No extra software to install
• Access from any computer with a web browser
• Full touchscreen and keyboard support
• Perfect for remote work or sharing the emulator with team members

• Features
• Prerequisites
• Installation
• Usage
  • Using Web Interface
  • Using ADB
  • Using Desktop scrcpy
  • Customizing Device Screen
• First Boot Process
• Container Logs
• Roadmap
• Troubleshooting
• Contributing
• License
• Contact

• 🌐 Web Interface: Access the emulator directly from your browser with the integratedscrcpy-web interface.
• 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 bothx86 andarm64 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.

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

    A non-zero output indicates KVM support.

To simplify the setup process, you can use the provideddocker-compose.yml file.

1. Clone the Repository:

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

2. Run Docker Compose:

   docker compose up -d

   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 athttp://localhost:8000.

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

1. Open your browser and go tohttp://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)

Note: First boot may take some time as the Android emulator needs to fully initialize. When everything is ready, the device will appear in the web interface as shown in the screenshot above.

If you need direct ADB access to the emulator:

adb connect localhost:5555adb devices

Expected Output:

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

For a native desktop experience, you can use scrcpy:

scrcpy -s localhost:5555

Note: Ensurescrcpy is installed on your host machine.Installation Guide

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 (whenGAPPS_SETUP=1): Adds essential Google services.
3. Rooting the Device (whenROOT_SETUP=1): Performs multiple reboots to:
   • Disable AVB verification
   • Remount system as writable
   • Install Magisk for root access
   • Reboot to apply root
4. Extras Copied: Pushes everything from theextras directory to/sdcard/Download so files like APKs or Magisk modules are ready for manual installation on the device.
5. Configuring optimal device settings

ROOT_SETUP andGAPPS_SETUP 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.

Important: The first boot can take 10-15 minutes to complete. You'll know the process is finished when you see the following log output:

Broadcast completed: result=0Success !!2025-04-22 13:45:18,724 INFO exited: first-boot (exit status 0; expected)

Note: If the Android emulator has restarted for any reason, it's recommended to restart the Docker container to reapply optimizations:

docker compose restart

This ensures the following optimizations are applied:

• Disabled animations for better performance
• Screen timeout set to 15 seconds
• Disabled rotation
• Custom DNS settings
• Airplane mode enabled (with WiFi still active)
• Data connection disabled

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

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

• Support for additional Android versions
• Integration with CI/CD pipelines
• Support ARM64 CPU architecture
• PICO GAPPS installation
• Support Magisk
• Adding web interface ofscrcpy
• Redirect all logs to container stdout/stderr

• ADB Connection Refused:

  • Ensure ADB Server is Running:

    adb start-server -a

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

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

    docker logs dockerify-android

• 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)
    • Configuring system settings
  • The process can take 10-15 minutes depending on your system performance
  • You can monitor progress withdocker logs -f dockerify-android

• Emulator Not Starting:

  • Check Container Logs:

    docker logs dockerify-android

• KVM Not Accessible:

  • Verify KVM Installation:

    lsmod| grep kvm

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

Contributions are welcome! To contribute:

1. Fork the Repository

2. Create a Feature Branch:

   git checkout -b feature/YourFeature

3. Commit Your Changes:

   git commit -m"Add Your Feature"

4. Push to the Branch:

   git push origin feature/YourFeature

5. Open a Pull Request

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

This project is licensed under theMIT License.

• Haroun EL ALAMI
• Email:haroun.dev@gmail.com
• GitHub:shmayro
• Twitter:@HarounDev