How to Install Docker on Debian

1 Scope

Platform: RK3328/RK3399/RK3568/RK3588
Operating System: Debian 10, Debian 11

2 Pre-installation checks and preparations

The recommended storage driver for Docker now is Overlay2. However, it may not be possible to install it directly if the root file system is already using OverlayFS. In that case, some adjustments need to be made to the partitions. There are several methods available and we will introduce them separately below. Please choose one according to your needs:

Method 1: Stop using OverlayFS on the root file system. This is the easiest way, but the "factory reset" function relies on OverlayFS, so this feature will not work.
Method 2: Create an additional partition to mount the /var/lib/docker directory. You need to plan the partition size in advance.
Method 3: Mount the /var/lib/docker directory on external storage devices such as USB flash drives and M.2 SSDs. The storage device needs to be formatted in ext4 format. This article mainly discusses the first two methods.

Precautions:

This operation will erase user data, so it is necessary to backup data in advance.
You need to update the firmware to a version on or after March 14, 2023, or update the boot.img separately.
The device node /dev/mmcblkX mentioned in the command is a fictional node and needs to be changed to the real device. The device node for eMMC is /dev/mmcblk2, and for TF card is /dev/mmcblk0.

3 Method 1: Make the root file system not use OverlayFS

Write specific content to /.init_wipedata and reboot:

sudo passwd root  # Create a password for the root user if it hasn't been done before.
su - root -c 'echo "overlayfs=disable" > /.init_wipedata'
sudo reboot

After rebooting, use the parted command to view the current partition layout. Normally, you should see that the root system is mounted in ext4 format, not overlay as before:

sudo apt update
sudo apt install parted
export DEV=/dev/mmcblkX  #needs to be changed to the real device
sudo parted -s ${DEV} unit MiB print

4 Method 2: Create an additional partition for Docker

Check the current partition layout

sudo apt update
sudo apt install parted fdisk
export DEV=/dev/mmcblkX #needs to be changed to the real device
sudo parted -s ${DEV} unit MiB print

Adjust the userdata partition to 8GB

Here, 8GB is used as an example. The partition size can be adjusted according to your needs:

sudo passwd root  # Create a password for the root user
su - root -c 'echo "overlayfs=enable userdata=8096" > /.init_wipedata'
sudo reboot

After reboot, confirm that the partition has been adjusted and you can see that the userdata partition is now 8GB：

export DEV=/dev/mmcblkX #needs to be changed to the real device
sudo parted -s ${DEV} unit MiB print

Create a new partition and format it:

(echo n; echo ""; echo ""; echo ""; echo w) | sudo fdisk ${DEV}
NUM=$(sudo parted ${DEV} print | awk 'NF > 1 {p = $1} END {print p}')  # Get the index of the last partition
sudo mkfs.ext4 ${DEV}p${NUM}

Mount the partition to the Docker data directory:

sudo mkdir /var/lib/docker
sudo blkid ${DEV}p${NUM}
# Configure automatic mounting
sudo vi /etc/fstab
# Add the following content to the end of the file (where UUID needs to be replaced with the actual one).
UUID=2efab5a5-8b74-41d2-8747-4c00fff8514a /var/lib/docker ext4 suid,dev,exec,auto,nouser,async,noatime,nofail 0 0
# Enter the following command to mount the partition:
sudo mount /var/lib/docker

5 Install Docker Engine

The docker installer uses iptables for nat, unfortunately Debian uses nftables, here we just setup Debian to use the legacy iptables:

[ -f /usr/sbin/iptables-legacy ] && sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
[ -f /usr/sbin/ip6tables-legacy ] && sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

Start installing Docker:

sudo apt install lsb-release wget
codename=$(lsb_release -c | awk '{print $2}')
version=$(lsb_release -sr | cut -d'.' -f1)
wget https://download.docker.com/linux/debian/dists/${codename}/pool/stable/arm64/containerd.io_1.6.9-1_arm64.deb
wget https://download.docker.com/linux/debian/dists/${codename}/pool/stable/arm64/docker-ce-cli_23.0.1-1~debian.${version}~${codename}_arm64.deb
wget https://download.docker.com/linux/debian/dists/${codename}/pool/stable/arm64/docker-buildx-plugin_0.10.2-1~debian.${version}~${codename}_arm64.deb
wget https://download.docker.com/linux/debian/dists/${codename}/pool/stable/arm64/docker-ce_23.0.1-1~debian.${version}~${codename}_arm64.deb
wget https://download.docker.com/linux/debian/dists/${codename}/pool/stable/arm64/docker-compose-plugin_2.6.0~debian-${codename}_arm64.deb
sudo dpkg -i ./containerd.io_1.6.9-1_arm64.deb \
  ./docker-ce_23.0.1-1~debian.${version}~${codename}_arm64.deb \
  ./docker-ce-cli_23.0.1-1~debian.${version}~${codename}_arm64.deb \
  ./docker-buildx-plugin_0.10.2-1~debian.${version}~${codename}_arm64.deb \
  ./docker-compose-plugin_2.6.0~debian-${codename}_arm64.deb

Verify if Docker has been installed successfully:

sudo docker info

Check if it is using the overlay2 storage driver.:

$ sudo docker info | grep storage -i
 Storage Driver: overlay2

6 Run Docker as a non-root user

sudo groupadd docker
sudo gpasswd -a ${USER} docker
sudo systemctl restart docker
sudo chmod a+rw /var/run/docker.sock

Let’s verify:

docker images

7 Testing Docker: Installing Nextcloud with docker

mkdir ~/nextcloud -p
docker run -d -p 8888:80  --name nextcloud  -v ~/nextcloud/:/var/www/html/ --restart=always --privileged=true  arm64v8/nextcloud

After installation, visit: http://device-ip-address:8888/ on your computer browser to view the nextcloud web page.

8 References

https://docs.docker.com/engine/install/debian/#install-from-a-package