DevMob

A Docker-based React Native development environment that eliminates setup complexity and provides a consistent, reproducible mobile development stack.

Table of Contents

• Features
• Prerequisites
• Installation
• Quick Start
• Usage
  • Environment Management
  • Project Creation
  • Development Server
  • Device Management
  • Debugging
  • Android SDK Management
  • Emulator Control
  • Wireless Debugging
  • Testing
  • Shell Access
• Examples
• Configuration
• Troubleshooting
• Contributing
• License
• Acknowledgments

Features

DevMob solves the "works on my machine" problem for React Native development by containerizing the entire mobile development stack. Key features include:

🚀 Project Management

• Dual Project Support: Create both Expo and React Native CLI projects
• Automatic Detection: Intelligent project type detection and command routing
• Quick Setup: One-command project creation with dependency installation

📱 Device & Emulator Support

• Android Emulator: Full GUI support
• Physical Devices: USB and wireless ADB connectivity
• Wireless Debugging: Automatic pairing and connection recovery
• Multi-Device: Support for multiple connected devices

🛠 Development Tools

• Metro/Expo Server: Functional and supporting hot reloading
• Testing Framework: command to run project tests directly in the current project
• Shell Access: Direct container access for advanced operations

🔧 Android SDK Management

• Dynamic Installation: Install any Android SDK version on-demand
• AVD Management: Automatic Android Virtual Device creation
• Build Tools: Complete Android build toolchain
• NDK Support: Native Development Kit included

🌐 Cross-Platform Development

• Android Support: Full Android development stack
• iOS Support: iOS development commands (requires macOS host)
• Expo Integration: Seamless Expo workflow support
• Universal Commands: Consistent CLI across project types

Prerequisites

System Requirements

• Operating System: Linux with Docker support
• Docker: Docker Engine and Docker Compose
• Storage: At least 7GB free space for both image and container

Installation

1. Clone the repository:

   git clone <repository-url>
   cd devmob

2. Make the script executable:

   chmod +x devmob

3. Initialize the environment:

   ./devmob init

4. Build the containers:

   ./devmob build

Quick Start

Get up and running with a new React Native project in minutes:

# 1. Initialize environment
./devmob init

# 2. Build containers
./devmob build

# 3. Install an Android SDK version
./devmob use 30

# 4. Start the emulator
./devmob emulator start

# 5. Create a new Expo project
./devmob expo

For React Native CLI projects:

# Create React Native CLI project
./devmob create

# Run on Android device/emulator
./devmob android

Usage

Initialize Environment

./devmob init

Creates .env file, sets up X11 forwarding, and prepares Android SDK directories.

Build Containers

./devmob build

Builds and starts Docker containers with all development tools.

Start/Stop Services

./devmob start [project_name]    # Start development server
./devmob stop                    # Stop all containers

View Logs

./devmob logs              # Show container logs

Project Creation

Create Expo Project

./devmob expo [project_name]

• Creates new Expo project with latest template
• Installs dependencies automatically
• Starts development server

Create React Native CLI Project

./devmob create [project_name]

• Initializes React Native CLI project
• Sets up build configuration
• Installs dependencies
• Starts Metro bundler

Development Server

Start Development Server

./devmob start [project_name]

• Automatically detects and stops existing Metro processes
• Starts fresh development server
• Supports hot reloading and live updates

Device Management

List Connected Devices

./devmob devices

Shows all connected Android devices and emulators.

Debugging

View React Native Logs

./devmob logcat [-s <device>]

Auto-detect device (recommended):

./devmob logcat

• Automatically detects connected devices
• Prioritizes real devices over emulators
• Shows only ReactNative and ReactNativeJS logs

Specify device manually:

./devmob logcat -s 192.168.1.100:5555
./devmob logcat -s emulator-5554

Run on Android

./devmob android [project_name]

• Auto-detects project type (Expo vs React Native CLI)
• Uses appropriate build command
• Installs and launches app on connected device/emulator

Run on iOS

./devmob ios [project_name]

• Supports iOS development (requires macOS host)
• Auto-detects project type
• Uses appropriate iOS build tools

Android SDK Management

Install SDK Version

./devmob use <version>

Example:

./devmob use 34    # Install Android 14 (API 34)

This command:

• Downloads and installs SDK platform
• Installs compatible build tools
• Downloads system images
• Creates AVD (Android Virtual Device)

Emulator Control

Start Emulator

./devmob emulator start

Launches the default_avd Android Virtual Device with GUI support.

Stop Emulator

./devmob emulator stop

Gracefully stops the running emulator instance.

Wireless Debugging

Connect to Device

./devmob connect <ip:port> [pair_port]

Example:

./devmob connect 192.168.1.100:5555

With pairing (for first-time connection):

./devmob connect 192.168.1.100:5555 43210

The command provides:

• Automatic pairing for new devices
• Connection retry logic
• Troubleshooting guidance
• Port change detection

Testing

Run Tests

./devmob test [project_name]

Executes the project's test suite using npm test.

Shell Access

Open Project Shell

./devmob shell [project_name]

Opens bash shell in the specified project directory for advanced operations.

Execute Custom Commands

./devmob <any_command>

Passes any command directly to the container:

./devmob ls -la                    # List files
./devmob npm install lodash       # Install package
./devmob logcat                   # View React Native logs (filtered)
./devmob adb logcat               # View all Android logs (unfiltered)

Examples

Complete Development Workflow

# 1. Setup environment
./devmob init
./devmob build

# 2. Install Android SDK
./devmob use 34

# 3. Start emulator
./devmob emulator start

# 4. Create and run Expo project
./devmob expo MyExpoApp
# Development server starts automatically

# 5. In another terminal, run on Android
./devmob android MyExpoApp

Physical Device Development

# 1. Enable wireless debugging on Android device
# Settings > Developer Options > Wireless Debugging

# 2. Connect to device
./devmob connect 192.168.1.100:5555

# 3. View logs while developing
./devmob logcat

# 4. Run your app
./devmob android MyProject

Configuration

Environment Variables

The .env file (created by ./devmob init) contains:

# User and display settings
UID=1000
GID=1000
DISPLAY=:0

# Hardware access
RENDER_GID=105
KVM_GID=104

# Localization
LANG=en_US.UTF-8
LANGUAGE=en_US:en
LC_ALL=en_US.UTF-8
TZ=Europe/Paris

# Android SDK configuration
SDK_VERSION=commandlinetools-linux-11076708_latest.zip
ANDROID_BUILD_VERSION=36
ANDROID_TOOLS_VERSION=36.0.0
NDK_VERSION=27.1.12297006
ANDROID_HOME=/opt/android

# Node.js and tools
NODE_VERSION=22.14
WATCHMAN_VERSION=4.9.0
CMAKE_VERSION=3.30.5

Container Configuration

Key docker-compose.yaml settings:

• Memory Limit: 8GB RAM, 2GB shared memory
• Network: Host network mode for device connectivity
• Volumes: Persistent Android SDK and project storage
• Devices: GPU, USB, and KVM access
• Security: Privileged mode for hardware access

Default Project Settings

• Default Project Name: devmobApp
• Default Device: pixel_6
• Container Name: devmob

Modify these in the devmob script header:

PROJECT=devmobApp
DEVICE_DEF="pixel_6"
CONTAINER=devmob

Troubleshooting

Common Issues

Emulator GUI Not Showing

# Enable X11 forwarding on your host
xhost +local:docker

# Check DISPLAY variable
echo $DISPLAY

# Verify GPU access
ls -la /dev/dri

Device Connection Issues

# Restart ADB
./devmob adb kill-server
./devmob adb start-server

Network Issues

Wireless Debugging Problems

1. Ensure both devices are on the same network
2. Check firewall settings
3. Restart wireless debugging on Android device
4. Try different connection ports

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

DevMob - Making React Native development consistent, reproducible, and hassle-free across all environments.