{"id":51119070,"url":"https://github.com/sulthonzh/android-docker-qemu","last_synced_at":"2026-06-25T00:30:40.988Z","repository":{"id":364724379,"uuid":"1268986929","full_name":"sulthonzh/android-docker-qemu","owner":"sulthonzh","description":"Run real Docker on Android (no root, no tricks) via QEMU + Debian 12. Survives phone reboots. Real dockerd + Compose v2.","archived":false,"fork":false,"pushed_at":"2026-06-14T07:16:32.000Z","size":60,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T09:09:04.147Z","etag":null,"topics":["android","arm64","debian","docker","docker-compose","home-server","learn-to-code","no-root","qemu","self-hosted","termux","virtual-machine"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sulthonzh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T07:02:04.000Z","updated_at":"2026-06-14T07:16:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sulthonzh/android-docker-qemu","commit_stats":null,"previous_names":["sulthonzh/android-docker-qemu"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sulthonzh/android-docker-qemu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fandroid-docker-qemu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fandroid-docker-qemu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fandroid-docker-qemu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fandroid-docker-qemu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sulthonzh","download_url":"https://codeload.github.com/sulthonzh/android-docker-qemu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fandroid-docker-qemu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34755061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","arm64","debian","docker","docker-compose","home-server","learn-to-code","no-root","qemu","self-hosted","termux","virtual-machine"],"created_at":"2026-06-25T00:30:40.847Z","updated_at":"2026-06-25T00:30:40.976Z","avatar_url":"https://github.com/sulthonzh.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Run Real Docker on Android — No Root, No Tricks, Just QEMU\n\n\u003e Turn any non-rooted Android phone into a real Docker host running Debian 12 in a QEMU virtual machine. Survives phone reboots. Uses real `dockerd` + Docker Compose v2, not a proot/udocker lookalike.\n\n📖 **Full step-by-step tutorial** → https://dev.to/sulthonzh/run-real-docker-on-android-no-root-no-tricks-just-qemu-15jn\n\n---\n\n## The architecture\n\n```\n                      Your computer\n                      (Mac or Linux)\n                            │\n                            │  ssh\n                            ▼\n  ╔══════════════════════════════════════════════════════╗\n  ║           ANDROID PHONE  (not rooted)                ║\n  ║                                                      ║\n  ║   ┌──────────────────────────────────────────────┐   ║\n  ║   │  TERMUX   (regular Android app)              │   ║\n  ║   │                                              │   ║\n  ║   │     • qemu-system-aarch64   emulator         │   ║\n  ║   │     • debian.qcow2          disk image       │   ║\n  ║   │     • boot scripts          auto-start VM    │   ║\n  ║   │     • sshd :8022            mgmt port        │   ║\n  ║   └──────────────────────┬───────────────────────┘   ║\n  ║                          │ launches                  ║\n  ║                          ▼                           ║\n  ║   ┌──────────────────────────────────────────────┐   ║\n  ║   │  QEMU VM   (real ARM64 hardware emulation)   │   ║\n  ║   │                                              │   ║\n  ║   │     • Debian 12 (bookworm)                   │   ║\n  ║   │     • real dockerd + Docker Compose v2       │   ║\n  ║   │     • systemd  (works, unlike proot)         │   ║\n  ║   │     • sshd :22  → forwarded to host :2222    │   ║\n  ║   └──────────────────────────────────────────────┘   ║\n  ╚══════════════════════════════════════════════════════╝\n\n  Two SSH targets (run from your computer):\n\n    ssh phone-termux   →   port 8022   →   Termux shell\n    ssh phone-vm       →   port 2222   →   Debian VM\n```\n\n**Why QEMU and not proot-distro / udocker?** Those don't give you a real kernel — no systemd, no cgroups, no real namespaces. Docker refuses to start, or containers aren't isolated. QEMU gives you a real Linux kernel at the cost of speed (~10–25× overhead from TCG software emulation).\n\n---\n\n## What you get\n\n- ✅ A real Debian 12 VM running inside your phone\n- ✅ Real `dockerd` + Docker Compose v2 (not a compatibility layer)\n- ✅ Survives phone reboots (via Termux:Boot)\n- ✅ Manageable from your computer via SSH, like any remote Docker host\n- ✅ Works on any non-rooted Android phone with ~6 GB RAM\n\n---\n\n## Requirements\n\n| Requirement | Why |\n|---|---|\n| Android phone, **not rooted**, ~6 GB+ RAM | QEMU needs RAM; rooting would void the point |\n| Termux (from F-Droid, not Play Store) | Play Store version is deprecated and broken |\n| Termux:Boot (from F-Droid) | Auto-starts the VM after phone reboot |\n| Computer on the same Wi-Fi as the phone | For SSH (Tailscale works too, out of scope here) |\n| ~5 GB free storage on the phone | Debian image + Docker images |\n| Patience (cold boot takes 20–30 min) | TCG software emulation is slow — fundamental limitation |\n\n---\n\n## Quick start\n\n**Easiest: pipe install.sh straight from GitHub** (recommended once you've reviewed [what it does](https://github.com/sulthonzh/android-docker-qemu/blob/main/install.sh)):\n\n```bash\n# Run this on BOTH your phone (inside Termux) and your computer (Mac/Linux).\n# The installer auto-detects which device it's on and does the right thing.\ncurl -fsSL https://raw.githubusercontent.com/sulthonzh/android-docker-qemu/main/install.sh | bash\n```\n\n**Safer: download and review first** (recommended for first-time users):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/sulthonzh/android-docker-qemu/main/install.sh -o install.sh\nless install.sh                # audit it\nbash install.sh                # then run it\n```\n\n**Or: clone the repo manually** (if you want to keep a local copy for inspection/contribution):\n\n```bash\ngit clone https://github.com/sulthonzh/android-docker-qemu\ncd android-docker-qemu\n./install.sh                   # or ./run.sh, same thing minus the auto-download\n```\n\n### Prerequisites (manual, ~5 minutes — Android restrictions make these unavoidable)\n\nOn your phone:\n\n1. **Install Termux** from [F-Droid](https://f-droid.org/packages/com.termux/) (NOT the Play Store version — it's deprecated and broken)\n2. **Install Termux:Boot** from [F-Droid](https://f-droid.org/packages/com.termux.boot/), then **open it once** (this registers the BOOT_COMPLETED receiver — Android requires the manual open)\n3. Open Termux and run:\n   ```bash\n   termux-setup-storage    # tap \"Allow\" on the Android dialog\n   pkg update \u0026\u0026 pkg install -y git curl\n   ```\n\nOn your computer: install Docker ([Docker Desktop](https://www.docker.com/products/docker-desktop/), [Colima](https://github.com/abiosoft/colima), or [OrbStack](https://orbstack.dev/) on Mac; `docker.io` on Linux) and generate an SSH key (`ssh-keygen -t ed25519`).\n\n### What happens after you run the installer\n\n**On the phone** (Termux auto-detected): installer hands off to `setup-phone.sh`, which:\n- Installs QEMU and dependencies (~2 min)\n- Downloads + resizes the Debian 12 cloud image (~5 min)\n- Builds the cloud-init seed with your SSH key (prompts for GitHub username, or paste)\n- Installs the QEMU launcher + boot scripts\n- Starts the VM\n- Prints the phone's IP address\n\nThe VM then boots for **20–30 minutes** (TCG software emulation — fundamental limitation).\n\n**On your computer** (Mac/Linux auto-detected): installer hands off to `setup-computer.sh`, which:\n- Installs the `phone-*` helper scripts to `~/.local/bin/`\n- Adds `phone-vm` and `phone-termux` entries to `~/.ssh/config`\n- Copies your SSH public key to Termux (so you can manage the phone)\n- Creates a Docker context named `phone` pointing at the VM via SSH\n- Runs a connectivity test\n\n### Day-to-day usage\n\n```bash\nphone-healthcheck                  # full end-to-end health check\nphone-status                       # quick human-readable state summary\nphone-vm-start --wait              # start VM if not running, wait until ready\nphone-vm-stop                      # graceful ACPI shutdown\n\ndocker --context phone run --rm hello-world\ndocker --context phone compose -f docker/docker-compose.example.yml up -d\n```\n\n📖 **Read the full tutorial for the why behind every step** → https://dev.to/sulthonzh/run-real-docker-on-android-no-root-no-tricks-just-qemu-15jn\n\n### Non-interactive usage (for scripts / CI)\n\n```bash\n# Phone: fetch SSH key from GitHub, no prompts\ncurl -fsSL https://raw.githubusercontent.com/sulthonzh/android-docker-qemu/main/install.sh \\\n  | bash -s -- --github your-github-username\n\n# Computer: provide phone IP directly, no prompts\ncurl -fsSL https://raw.githubusercontent.com/sulthonzh/android-docker-qemu/main/install.sh \\\n  | bash -s -- --phone-ip 192.168.0.9\n\n# Either: preview without changes\ncurl -fsSL https://raw.githubusercontent.com/sulthonzh/android-docker-qemu/main/install.sh \\\n  | bash -s -- --dry-run\n\n# Either: keep the extracted repo instead of cleaning up\ncurl -fsSL https://raw.githubusercontent.com/sulthonzh/android-docker-qemu/main/install.sh \\\n  | bash -s -- --keep\n```\n\n---\n\n## What's in this repo\n\n```\n.\n├── install.sh                   curl-pipeable installer (download + extract + dispatch)\n├── run.sh                       Local entry point — detects phone vs computer, dispatches\n├── setup-phone.sh               Phone setup (runs inside Termux)\n├── setup-computer.sh            Computer setup (Mac/Linux)\n├── README.md                    You are here\n├── SECURITY.md                  What the scripts do/don't do (audit reference)\n├── PLAYBOOK.md                  The full 1500-line engineering playbook (deep dive)\n├── termux/                      Files that install ON THE PHONE (Termux side)\n│   ├── boot-debian-mon.sh       QEMU launcher script\n│   ├── 01-start-vm.sh           Termux:Boot auto-start hook\n│   └── cloud-init/\n│       ├── user-data            VM cloud-init config (TEMPLATE — replace SSH key!)\n│       └── meta-data            VM instance metadata\n├── vm/                          Files that install INSIDE THE VM\n│   ├── docker-daemon.json       /etc/docker/daemon.json — tuned for TCG\n│   └── zramswap.default         /etc/default/zramswap — ZRAM swap config\n├── mac/                         Mac/Linux helper scripts (installed by setup-computer.sh)\n│   ├── phone-healthcheck        End-to-end verification with exit code\n│   ├── phone-status             Human-readable current state\n│   ├── phone-vm-start           Start the VM (with optional --wait)\n│   ├── phone-vm-stop            Graceful ACPI shutdown\n│   ├── phone-vm-restart         Stop + start\n│   ├── phone-vm-console         Attach to QEMU monitor (Ctrl-C to detach)\n│   └── phone-vm-logs            Tail recent VM kernel logs\n├── docker/\n│   └── docker-compose.example.yml   Minimal test stack (traefik/whoami)\n└── docs/\n    └── TROUBLESHOOTING.md       Solutions for the 5 most common failures\n```\n\n---\n\n## Performance expectations (be honest with yourself)\n\n| Operation | Time | Why |\n|---|---|---|\n| Cold QEMU boot | 20–30 min | TCG translates every ARM instruction in software |\n| `docker pull hello-world` | ~75 sec | TLS handshake is slow under emulation |\n| `docker pull \u003creal image\u003e` | 5–15 min | First pull is always slowest |\n| `docker compose up` (cached) | ~10 sec | After images are cached, it's fine |\n| Container runtime perf | 10–25× slower than native | Software emulation tax |\n\nThis is **not** a production server. It's a learning environment, a CI experiment, a self-hosted playground that uses hardware you already own. If you need real performance, root the phone or use a Raspberry Pi.\n\n---\n\n## Why this exists\n\nEvery \"Docker on Android\" tutorial I found was lying — either it required root, or it used `proot-distro`/`udocker` which **aren't Docker** (no systemd, no cgroups, no real isolation). This repo is the only path I found that gives you **a real Docker daemon running real containers on a non-rooted phone**: Debian in QEMU, inside Termux.\n\n---\n\n## Troubleshooting\n\nSee **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** for the 5 most common failures and their fixes. For everything else, open an [Issue](https://github.com/sulthonzh/android-docker-qemu/issues).\n\n---\n\n## Star this repo ⭐\n\nIf this saved you a weekend of trial and error, give it a star. It helps other people find it — \"no-root Docker on Android\" is a common question and most of the answers are bad.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE). Do whatever you want. Attribution appreciated but not required.\n\n---\n\n## Acknowledgments\n\n- The **Termux** team — without Termux this entire approach would be impossible.\n- The **QEMU** project — software emulation of aarch64 is a marvel.\n- **Debian Cloud Team** — for publishing clean cloud images that just work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsulthonzh%2Fandroid-docker-qemu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsulthonzh%2Fandroid-docker-qemu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsulthonzh%2Fandroid-docker-qemu/lists"}