Setup Docker Remote on Raspberry Pi 5 from Windows

Task: Setup Docker Context for Remote Execution on Raspberry Pi 5 from Windows 11

Goal: The objective is to configure your Windows 11 environment (using WSL and PowerShell) to seamlessly execute Docker commands on a remote Raspberry Pi 5, treating it as a local Docker host through a Docker context.

Prerequisites:

1. Raspberry Pi 5: Must be running an operating system that supports Docker (e.g., Raspberry Pi OS) and have Docker installed. Also, you must have SSH enabled on your Raspberry Pi 5.
2. Windows Subsystem for Linux (WSL): You need a WSL distribution (e.g., Ubuntu) installed on your Windows machine.
3. SSH Key Pair: A generated SSH key pair with the public key copied to your Raspberry Pi.

Steps:

1. SSH Configuration in WSL (~/.ssh/config)

• Purpose: This step configures SSH to allow passwordless access to your Raspberry Pi using the SSH key.
• Action: Edit the ~/.ssh/config file within your WSL environment to include the following configuration. If the file doesn’t exist, create it.

# Open the config file in your WSL environment (replace with your editor)
nano ~/.ssh/config

Add the following to the file, adjusting the IdentityFile path:

  Host rpi5
    HostName raspberrypi5.local
    User rpi
    Port 22065
    IdentityFile "C:\Users\srees\.ssh\rpi5"

• Explanation:
• Host rpi5: A convenient alias for referring to the Raspberry Pi connection in SSH commands.
• HostName: The hostname or IP address of your Raspberry Pi. Using .local assume your network supports mDNS. You can use the IP address if your Raspberry Pi doesn’t have a hostname.
• User: The username you use to log into the Raspberry Pi.
• Port: The port number your SSH server is listening on. Defaults to port 22 if not changed.
• IdentityFile: The path to your private SSH key on your Windows machine. Note, you’re pointing to Windows file system using the Windows path.

2. Creating a Docker Context

• Purpose: This step creates a Docker context named “rpi5” that allows you to target your Raspberry Pi’s Docker daemon instead of your local one.
• Action: Run the following command in your WSL environment:

  docker context create rpi5 --docker "host=ssh://rpi5"
  

• Explanation:
• docker context create rpi5: Creates a new Docker context named rpi5.

• --docker "host=ssh://rpi5": Specifies that this context will connect to the Docker daemon over SSH using the rpi5 host alias defined in your ~/.ssh/config.

• Verification:
• docker context ls: Lists all available Docker contexts. You should see rpi5 listed.
• docker context inspect rpi5: Displays the detailed configuration of the rpi5 Docker context.

3. PowerShell Alias for Convenience

• Purpose: This section streamlines the process of using the remote Docker context by creating an alias in PowerShell.

• Action:

  1. Create PowerShell Profile: If it doesn’t exist yet create it.

       New-Item -Path $PROFILE -ItemType File -Force
     

  2. Edit PowerShell Profile: Open your PowerShell profile file in Notepad.

       notepad $PROFILE
     

  3. Add Function: Add the following function to your PowerShell profile file:

       function docker-rpi5 {
           param(
               [Parameter(ValueFromRemainingArguments=$true)]
               [String[]]$args
           )
           docker --context rpi5 @args
       }
     

  4. Save and Reload: Save the profile and close Notepad. Then, reload it in your PowerShell session:

     . $PROFILE
     

• Explanation:
• $PROFILE: A built-in PowerShell variable that points to the path of your PowerShell profile script. This script is automatically executed every time a new PowerShell session starts.
• function docker-rpi5: Defines a new PowerShell function named docker-rpi5.
• param(...): Defines the function parameters, capturing any arguments passed to docker-rpi5
• docker --context rpi5 @args: Executes the docker command with the --context rpi5 argument and passes all arguments given to docker-rpi5. This ensures all command line options are forwarded to docker.

4. Verification

• Test Alias: Run the following commands in PowerShell to confirm the setup works:

  docker-rpi5 ps
  docker-rpi5 images
  

• Explanation
• docker-rpi5 ps: Lists the currently running containers on your Raspberry Pi.
• docker-rpi5 images: Lists images stored on your Raspberry Pi.

• Profile File Content Check: To see if your changes to profile file are correct

  Get-Content $PROFILE
  

• Profile File Existence Check:

  Test-Path $PROFILE
  

• True: The profile exists.
• False: You need to create it.

5. Using the Remote Docker Context

• From now on, use the alias docker-rpi5 instead of docker when you want to run commands on your Raspberry Pi. For example:

  docker-rpi5 run -d -p 8080:80 nginx
  docker-rpi5 logs <container_id>
  docker-rpi5 stop <container_id>
  

Summary:

You’ve successfully set up your Windows environment to run Docker commands on a remote Raspberry Pi. Now, you can use the docker-rpi5 alias from PowerShell as if the Raspberry Pi were your local Docker host.

Important Considerations:

• Firewall: Ensure that the necessary ports (especially port 22 or your SSH port, if it is different) are open on both your Windows firewall and your Raspberry Pi’s firewall.
• Network: Your Windows machine and Raspberry Pi must be on the same network to communicate with each other.
• Performance: Running Docker containers remotely may be slower than local execution. Consider network bandwidth and Raspberry Pi processing power when planning your container deployment.

This comprehensive documentation should help you set up your remote Docker environment effectively.

If you have any questions or feedback, feel free to email me.

Happy blogging!