Custom Redroid Image: From Source Code Build to Feature Enhancement

Wed, 17 Sep 2025 00:00:00 +0000

Overview

Redroid (Remote Android) is a container-based Android runtime environment that can run a complete Android system on Linux servers. This article provides a detailed guide on how to build a fully functional custom Redroid image from AOSP source code, integrating advanced features such as GPS positioning, battery management, and Magisk Root.

Use Cases

Mobile application development and testing
Automated testing environment setup
Android reverse engineering and security research
Cloud-based Android service deployment

Prerequisites

Before starting, please ensure your environment meets the following requirements:

Hardware Requirements

CPU: Recommended 8+ cores, supporting x86_64 architecture
Memory: At least 16GB RAM, 32GB recommended
Storage: At least 100GB available space (SSD recommended)

Software Environment

Operating System: Ubuntu 20.04/22.04 LTS or other modern Linux distributions
Docker: Version 20.10 or higher
Git: Version 2.25 or higher
Python 3: For running build scripts

Network Requirements

Stable network connection (large amount of source code to download)
If encountering network issues, recommend using Tsinghua mirror sources

Step 1: Environment Setup and Source Code Download

1.1 Create Working Directory

1
2
3

# Create dedicated working directory
cd /data
mkdir redroid && cd redroid

Install Google Repo Tool

Repo is a tool developed by Google for managing multiple Git repositories, essential for AOSP projects.

# Download and install repo tool
curl -k https://storage.googleapis.com/git-repo-downloads/repo > /usr/local/bin/repo
chmod a+x /usr/local/bin/repo

# Configure Git user information (required)
git config --global user.email "your-email@example.com"
git config --global user.name "YourName"

Note: Please replace the email and username with your actual information.

Initialize AOSP Source Repository

# Initialize repo using Tsinghua mirror for accelerated download
repo init -u https://mirrors.tuna.tsinghua.edu.cn/git/AOSP/platform/manifest \
    --git-lfs --depth=1 -b android-15.0.0_r36

# Add Redroid-specific local manifest configuration
git clone https://git.coderkang.top/Android/local_manifests.git \
    .repo/local_manifests -b 15.0.0

Sync Source Code

1
2

# Start syncing source code (time-consuming, please be patient)
repo sync -c

Tip: Initial sync may take 2-4 hours, depending on network conditions. Recommend using screen or tmux to run in background.

Step 2: Magisk Module Integration

Magisk is a popular Android Root solution that provides system-level permission management.

Extract Magisk Components

1
2
3

# Enter Magisk directory and execute extraction script
cd /data/redroid/vendor/magisk
python3 magisk.py

This script will automatically download the latest version of Magisk APK and extract necessary binary files and modules, integrating them into the system image.

Step 3: Apply Custom Patches

Download and Apply Redroid Patches

# Return to main directory
cd /data

# Get Redroid-specific patch set
git clone https://git.coderkang.top/Android/redroid-patches.git

# Apply all patches to source code
./redroid-patches/apply-patch.sh /data/redroid

These patches include:

GPS Functionality: Enable location service support
Battery Management: Simulate battery status and power management
Network Enhancement: Improve network connection stability
Performance Optimization: Performance tuning for container environments

Step 4: Docker Build Environment Setup

Create Build Container

# Get build tools
git clone https://git.coderkang.top/Android/redroid-doc.git
cd redroid-doc/android-builder-docker

# Build Docker image (contains all build dependencies)
docker build \
    --build-arg userid=$(id -u) \
    --build-arg groupid=$(id -g) \
    --build-arg username=$(id -un) \
    -t redroid-builder .

Start Build Environment

# Start build container, mount source code directory
docker run -it --rm \
    --hostname redroid-builder \
    --name redroid-builder \
    -v /data/redroid:/src \
    redroid-builder

Step 5: Compile Android System

Configure Build Environment

# Execute the following commands inside the container
cd /src

# Initialize build environment
. build/envsetup.sh

# Select build target (ARM64 architecture, user debug version)
lunch redroid_arm64_only-ap3a-userdebug

Start Compilation

1
2

# Start compilation process (time-consuming, recommend using -j parameter to specify parallelism)
m -j$(nproc)

Compilation Time: Depending on hardware configuration, compilation usually takes 1-3 hours.

Step 6: Image Packaging and Deployment

Create Docker Image

After compilation is complete, the generated system files need to be packaged into a Docker image.

# Exit build container, return to host machine
exit

# Enter compilation output directory
cd /data/redroid/out/target/product/redroid_arm64_only

# Mount system images (read-only)
sudo mount system.img system -o ro
sudo mount vendor.img vendor -o ro

# Package as Docker image
sudo tar --xattrs -c vendor -C system --exclude="./vendor" . | \
    docker import -c 'ENTRYPOINT ["/init", "androidboot.hardware=redroid", "ro.setupwizard.mode=DISABLED"]' \
    - redroid:custom

# Unmount image files
sudo umount system vendor

Verify Image

# View created image
docker images | grep redroid

# Test starting container
docker run -itd --rm --memory-swappiness=0 \
    --name redroid-test \
    -p 5555:5555 \
    redroid:custom

Function Verification and Usage

Verify Root Permissions

# Connect to Redroid container
adb connect localhost:5555

# Verify Root permissions
adb shell su -c "id"

Verify GPS Functionality

1
2

# Check GPS service status
adb shell dumpsys location

Verify Battery Management

1
2

# View battery status
adb shell dumpsys battery

Common Issues and Solutions

Compilation Errors

Issue: Insufficient memory causing compilation failure

1
2

# Solution: Reduce parallelism
m -j4  # Use fewer parallel tasks

Issue: Insufficient disk space

1
2

# Solution: Clean compilation cache
make clean

Runtime Issues

Issue: Container cannot start

# Check kernel modules
lsmod | grep binder
lsmod | grep ashmem

# If missing, load modules
sudo modprobe binder_linux
sudo modprobe ashmem_linux

Issue: ADB connection failure

1
2
3

# Restart ADB service
adb kill-server
adb start-server

Optimization Recommendations

Performance Optimization

Memory Configuration: Allocate sufficient memory to containers (recommended 4GB+)
CPU Configuration: Enable CPU hotplug support
Storage Optimization: Use SSD storage to improve I/O performance

Security Considerations

Network Isolation: Use custom Docker networks
Permission Control: Limit container permissions, avoid privileged mode
Data Persistence: Properly configure data volume mounts

Summary

Through the detailed guidance in this article, you have successfully built a fully functional custom Redroid image. This image integrates advanced features such as GPS, battery management, and Magisk Root, meeting various development and testing needs.

In practical use, you can further customize system configurations, add more functional modules, or optimize performance parameters according to specific requirements. Redroid’s flexibility makes it an ideal choice for Android development and testing.

Next Steps

Explore more Magisk module integrations
Configure Continuous Integration/Continuous Deployment (CI/CD)
Set up multi-instance cluster environments
Integrate automated testing frameworks

Android on Kang's Blog