Set up SSH

The Docker context is controlled exclusively through SSH, as the root user. This requires setting up some keys to allow the pi user to access the root user’s account.

Although you will not need to interact with the root user’s shell directly, the pi user will be granted full access to root via SSH.

graph LR;
    subgraph Raspberry Pi
        pi[User: pi]
        root[User: root]
        pi -->|Docker SSH context to root@localhost| root
    end

RemoteComputer[Personal Workstation] -->|ssh pi@pi| pi

Docker == root == pi

SSH is used here almost like sudo. The pi user should be treated with the same respect as the root user, as it will be granted full root access through SSH (to localhost).

Create a new SSH key

You need to create a new SSH key for the pi user.

Unencrypted SSH keys are used for convenience

To connect to the Docker context requires that your SSH key be already decrypted.

There’s only two ways to do that:

Create an unencrypted SSH key, so that no passphrase is ever required.

-or-

Set up an ssh-agent to decrypt and load the unencrypted key into resident memory, so that your key can be used without requiring a passphrase.

For the sake of convenience, this guide will use the first method, and create a new unencrypted SSH key, living in the pi user’s home directory: /home/pi/.ssh/id_ed25519. The security of this key depends upon the physical and network security of the device (including SD card). Any user gaining entry to the pi user’s account will have access to the key, and no passphrase is required to use the key.

If you wish to enhance the security of your SSH key, please read the Arch Wiki article on SSH keys, which covers generating secure SSH keys, setting a passphrase, and setting up an ssh-agent with Keychain.

You may also protect the integrity of the SD card (at rest) with full disk encryption and remote unlock via SSH.

Create a new SSH key (without a passphrase):

Run this on the Raspberry Pi

ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519

Authorize the key of the pi user to connect as root

All interaction with Docker is done over SSH as the root user, so for the pi user to control Docker, they need to be able to SSH to localhost as the root user.

Add the pi user’s key to the root user’s /root/.ssh/authorized_keys file:

Run this on the Raspberry Pi

cat ~/.ssh/id_ed25519.pub | sudo tee -a /root/.ssh/authorized_keys

Create a config named pi in your ~/.ssh/config:

Run this on the Raspberry Pi

cat <<EOF >> ~/.ssh/config
Host pi
    User root
    Hostname localhost
    ControlMaster auto
    ControlPersist yes
    ControlPath /tmp/ssh-%u-%r@%h:%p
EOF

Test the connection is working:

Run this on the Raspberry Pi

ssh pi whoami

Accept the key fingerprint it offers:

(stdout)

The authenticity of host 'localhost (::1)' can't be established.
ED25519 key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

If it worked, you should see the output of whoami which should print the username root (which is the user configured by SSH).