Skip to content

Instantly share code, notes, and snippets.

@manoedinata

manoedinata/Running Docker on Phone + postmarketOS.md

Last active February 1, 2026 10:09
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save manoedinata/d93549d85acbee94f37683fa6cbd626e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save manoedinata/d93549d85acbee94f37683fa6cbd626e to your computer and use it in GitHub Desktop.
Download ZIP
Running Docker on postmarketOS
Raw
Running Docker on Phone + postmarketOS.md

Running Docker on Phone + postmarketOS

Tip

See the blog post: https://mdinata.my.id/blogs/docker-on-postmarketos/

With postmarketOS and modified kernel (see https://blog.hypriot.com/post/verify-kernel-container-compatibility/), it's possible to natively run Docker on phone. Since postmarketOS runs Alpine Linux natively, there's no need to run VMs, chroot, or whatever it is. Just native. Ain't that cool?

Device

I have Samsung Galaxy J4 (newly ported), with downstream kernel 3.18. To get Docker working on it, I have to apply some changes:

  • Enable some kernel features (mostly needed by other devices)
  • Enabling cgroup mounts through OpenRC
  • Switching from iptables to iptables-legacy

Let's break 'em down!

Enabling Required Kernel Features

TBA

Installing Docker

This should be straightforward.

sudo apk add docker docker-compose
sudo addgroup $USER docker

Enabling cgroup Mounts

It seems like cgroupv2 isn't supported in my device. Dunno why, it's just not appearing on /sys/fs/cgroup.

As a workaround, switch OpenRC cgroup mounts to hybrid mode, where both cgroups version 1 and 2 will be mounted on /sys/fs/cgroup.

Open /etc/rc.conf, search for rc_group_mode, then set it to hybrid or legacy.

# This sets the mode used to mount cgroups.
# "hybrid" mounts cgroups version 2 on /sys/fs/cgroup/unified and
# cgroups version 1 on /sys/fs/cgroup.
# "legacy" mounts cgroups version 1 on /sys/fs/cgroup
# "unified" mounts cgroups version 2 on /sys/fs/cgroup
rc_cgroup_mode="hybrid"

image

Switching to iptables-legacy

Trying to manually run dockerd results in this error:

INFO[2024-11-10T11:34:25.208702609+07:00] unable to detect if iptables supports xlock: 'iptables --wait -L -n': `# Warning: iptables-legacy tables present, use iptables-legacy to see them
iptables v1.8.10 (nf_tables): Could not fetch rule set generation id: Invalid argument`  error="exit status 4"

Switching to iptables-legacy seems to fix this problem, whether permanently or temporary. To switch, link iptables-legacy to the original iptables binary.

sudo apk add iptables-legacy

# Rename original iptables
sudo mv /usr/sbin/iptables /usr/sbin/iptables-original
sudo mv /usr/sbin/ip6tables /usr/sbin/ip6tables-original
sudo mv /usr/sbin/arptables /usr/sbin/arptables-original
sudo mv /usr/sbin/ebtables /usr/sbin/ebtables-original

# Link iptables-legacy to iptables
sudo ln -s /usr/sbin/iptables-legacy /usr/sbin/iptables
sudo ln -s /usr/sbin/ip6tables-legacy /usr/sbin/ip6tables
sudo ln -s /usr/sbin/arptables-legacy /usr/sbin/arptables
sudo ln -s /usr/sbin/ebtables-legacy /usr/sbin/ebtables

Starting Docker

sudo service docker start
sudo rc-update add docker default

Testing

image

image

@olaioo
Copy link

olaioo commented Aug 1, 2025

First, I would like to thank you for the guide. I was facing this issue on the xaiomi-miatoll. But, I had also another problem, the kernel provide by the postmarketos for my device, it doesn't come with this iptable_raw module. So, after a lot of searching I found that this module isn't required to any version before docker v27.5.1. Thus, I installed manually this old docker version and so far, the docker is working properly on my device.

@manoedinata
Copy link
Author

manoedinata commented Aug 1, 2025

First, I would like to thank you for the guide. I was facing this issue on the xaiomi-miatoll. But, I had also another problem, the kernel provide by the postmarketos for my device, it doesn't come with this iptable_raw module. So, after a lot of searching I found that this module isn't required to any version before docker v27.5.1. Thus, I installed manually this old docker version and so far, the docker is working properly on my device.

Thanks for the heads up! Is this problem occured after switching to iptables-legacy? Since I saw that IP_NF_RAW is needed with iptables-legacy.

I'll update the guide to show another workaround by using older Docker version. Thanks!

@olaioo
Copy link

olaioo commented Aug 8, 2025 •
edited
Loading

Huhh... I thought It was working just because the container was up, but the docker networking wasn't working. I had to rebuild the kernel with these modules: IP_NF_RAW and IP6_NF_RAW, they were the only modules that it was missing from the "Generally Necessary" section from the check-config.sh. There is a wiki post on postmarketos wiki that helped me rebuilding the kernel, the link is: https://wiki.postmarketos.org/wiki/User:Wangxiaohu/Docker. And the script to check the modules, you can find here: https://blog.hypriot.com/post/verify-kernel-container-compatibility/.

After the installation of the new kernel build (including those modules), I disabled the nftables service and had to "downgrade" to the iptables-legacy (exactly as you describe in this guide), and, NOW, it's working properly!!! I'm using the last version of the docker, by the way.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment