Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

feat(rootfs): ship the user guide in the guest with podroid-docs

ExTv5ebe8e9bf1cb
diff --git a/.gitignore b/.gitignore
index 77512e6..efd4fb1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,6 +32,10 @@ local.properties
*.tar.gz
config.log
+# docs/guide staged into the rootfs Docker build context by build_rootfs()
+# in build-all.sh (docs/ lives outside build-rootfs/, which is the context)
+/build-rootfs/docs-guide/
+
# Generated assets (built by docker-build-initramfs.sh)
app/src/main/assets/vmlinuz-virt
app/src/main/assets/initrd.img
diff --git a/README.md b/README.md
index 15e17b2..aa83af7 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,10 @@ podroid-forward clean # remove every rule you added, in one go
# SSH in from your laptop (enable SSH in the setup wizard or Settings)
ssh root@<phone-ip> -p 9922 # password: podroid
+
+# read this documentation with no network connection
+podroid-forward add 9980 9980 tcp # forward the docs port to the phone
+podroid-docs # serves docs/guide at http://127.0.0.1:9980
```
Setup, the two backends, networking, the X11 viewer and troubleshooting all live in the **[documentation](https://extv.github.io/Podroid/guide/)**.
diff --git a/build-all.sh b/build-all.sh
index b575e21..3ea89e8 100755
--- a/build-all.sh
+++ b/build-all.sh
@@ -123,6 +123,13 @@ build_rootfs() {
log "Building Alpine rootfs squashfs..."
local sysver
sysver=$(grep -E '^[[:space:]]*versionCode[[:space:]]*=' "${SCRIPT_DIR}/app/build.gradle.kts" | grep -oE '[0-9]+' | head -1)
+
+ # docs/guide/ lives outside build-rootfs/, the Docker build context below,
+ # so stage a fresh copy inside it for Dockerfile.rootfs to COPY in.
+ rm -rf "${SCRIPT_DIR}/build-rootfs/docs-guide"
+ mkdir -p "${SCRIPT_DIR}/build-rootfs/docs-guide"
+ cp "${SCRIPT_DIR}/docs/guide/"*.html "${SCRIPT_DIR}/docs/guide/style.css" "${SCRIPT_DIR}/build-rootfs/docs-guide/"
+
docker build -f "${SCRIPT_DIR}/build-rootfs/Dockerfile.rootfs" \
-t podroid-rootfs:latest \
--build-arg "SYSTEM_VERSION=${sysver:-0}" \
diff --git a/build-rootfs/Dockerfile.rootfs b/build-rootfs/Dockerfile.rootfs
index 7ef7fe7..a5f97f1 100644
--- a/build-rootfs/Dockerfile.rootfs
+++ b/build-rootfs/Dockerfile.rootfs
@@ -37,6 +37,9 @@ ENV SYSTEM_VERSION=${SYSTEM_VERSION}
ENV ALPINE_VERSION=${ALPINE_RELEASE}
COPY files /work/files
+# Staged by build_rootfs() in build-all.sh (docs/ lives outside this build
+# context); served in-guest by /usr/local/bin/podroid-docs.
+COPY docs-guide /work/docs-guide
COPY build-rootfs.sh /work/build-rootfs.sh
RUN chmod +x /work/build-rootfs.sh && /work/build-rootfs.sh
diff --git a/build-rootfs/build-rootfs.sh b/build-rootfs/build-rootfs.sh
index b95522a..f356f9b 100755
--- a/build-rootfs/build-rootfs.sh
+++ b/build-rootfs/build-rootfs.sh
@@ -115,6 +115,7 @@ cp /work/files/usr/local/bin/podroid-resize "$ROOTFS/usr/local/bin/"
cp /work/files/usr/local/bin/podroid-login "$ROOTFS/usr/local/bin/"
cp /work/files/usr/local/bin/podroid-getty "$ROOTFS/usr/local/bin/"
cp /work/files/usr/local/bin/podroid-backup "$ROOTFS/usr/local/bin/"
+cp /work/files/usr/local/bin/podroid-docs "$ROOTFS/usr/local/bin/"
# podroid-vsock-agent is COPY'd in from the vsock-builder Docker stage. Make
# sure it's executable (cross-arch COPY can lose the mode bit on some buildkit
# versions).
@@ -169,6 +170,14 @@ mkdir -p "$ROOTFS/etc/containers"
cp /work/files/etc/containers/storage.conf "$ROOTFS/etc/containers/storage.conf"
chmod 0644 "$ROOTFS/etc/containers/storage.conf"
+# Offline copy of the docs/guide site, staged into /work/docs-guide by
+# build_rootfs() in build-all.sh (this must run after the "Strip docs" rm -rf
+# above, or mksquashfs would ship nothing here). Served in-guest by
+# podroid-docs.
+mkdir -p "$ROOTFS/usr/share/doc/podroid"
+cp /work/docs-guide/*.html /work/docs-guide/style.css "$ROOTFS/usr/share/doc/podroid/"
+chmod 0644 "$ROOTFS/usr/share/doc/podroid/"*
+
# Hostname (read by podroid-bootstrap via `hostname -F /etc/hostname`)
echo "podroid" > "$ROOTFS/etc/hostname"
echo "127.0.0.1 localhost podroid" > "$ROOTFS/etc/hosts"
diff --git a/build-rootfs/files/usr/local/bin/podroid-docs b/build-rootfs/files/usr/local/bin/podroid-docs
new file mode 100644
index 0000000..0d5b760
--- /dev/null
+++ b/build-rootfs/files/usr/local/bin/podroid-docs
@@ -0,0 +1,21 @@
+#!/bin/sh
+# Serves the offline copy of the Podroid documentation (docs/guide/, mirrored
+# into the squashfs at build time by build-rootfs.sh) over plain HTTP, so it
+# can be read from a browser with no network connection.
+#
+# Runs in the foreground until interrupted (Ctrl-C); forward the port to read
+# it from the phone's own browser:
+# podroid-forward add 9980 9980 tcp
+# then open http://127.0.0.1:9980
+
+DOCROOT=/usr/share/doc/podroid
+
+if [ ! -d "$DOCROOT" ]; then
+ echo "podroid-docs: $DOCROOT not found" >&2
+ exit 1
+fi
+
+echo "Serving the Podroid docs at http://127.0.0.1:9980 (Ctrl-C to stop)"
+echo "From the phone: podroid-forward add 9980 9980 tcp, then open http://127.0.0.1:9980"
+
+exec busybox httpd -f -p 9980 -h "$DOCROOT"
diff --git a/docs/guide/getting-started.html b/docs/guide/getting-started.html
index 3e8e9be..a69f70a 100644
--- a/docs/guide/getting-started.html
+++ b/docs/guide/getting-started.html
@@ -121,6 +121,12 @@
<span class="c"># password: podroid</span></code></pre>
<p>Port 9922 is the default; see the <a href="networking.html">Networking &amp; ports</a> page for how SLIRP forwarding works and how to add more port rules.</p>
+ <h2>Offline docs</h2>
+ <p>This guide also ships inside the guest, for reading with no network connection. From the terminal:</p>
+ <pre><code><span class="p">$</span> podroid-forward add 9980 9980 tcp
+<span class="p">$</span> podroid-docs</code></pre>
+ <p>Open <code>http://127.0.0.1:9980</code> in the phone's browser. <code>podroid-docs</code> serves <code>/usr/share/doc/podroid</code> with busybox's <code>httpd</code> and runs in the foreground until you stop it with Ctrl-C.</p>
+
<div class="callout warn">
<span class="label">VM killed when you switch apps?</span>
<p>If you see "QEMU crashed (SIGKILL)" after backgrounding the app, Android's phantom-process killer is terminating the QEMU process. This is an OS-level restriction, not a bug. See <a href="limitations.html">Limitations &amp; troubleshooting</a> for the workaround.</p>