# Perform remote Docker builds on an Arm server

## In this learning path

- [Introduction](https://learn.arm.com/learning-paths/cross-platform/docker/)
- [Build, run, and share a Docker image](https://learn.arm.com/learning-paths/cross-platform/docker/build/)
- [Build multi-architecture images with Docker buildx](https://learn.arm.com/learning-paths/cross-platform/docker/buildx/)
- [Perform remote Docker builds on an Arm server](https://learn.arm.com/learning-paths/cross-platform/docker/remote/)
- [Use Docker manifest to create multi-architecture images](https://learn.arm.com/learning-paths/cross-platform/docker/manifest/)
- [Check container images for multi-architecture support](https://learn.arm.com/learning-paths/cross-platform/docker/check-images/)
- [Next Steps](https://learn.arm.com/learning-paths/cross-platform/docker/_next-steps/)

## Before you begin
Building Docker images for the Arm architecture on the non-Arm machine on your desk using emulation may be slow. This section explains how to use the `docker context` command to build an image for the Arm architecture using a remote machine accessible via SSH. Docker should also be installed on a remote Arm machine which can be reached via SSH without password.

For more information about SSH configuration refer to [SSH](https://learn.arm.com/install-guides/ssh/).

To learn how to create an Arm virtual machine using a cloud service provider refer to [Get started with Arm-based cloud instances](https://learn.arm.com/learning-paths/servers-and-cloud-computing/csp/).

## Build a Docker image from a Dockerfile
This section contrasts a local build for the x86_64 architecture and a remote build for the Arm architecture. On your local computer, create a new directory and use a text editor to copy the two lines below into a file named `Dockerfile`, or reuse the same file from the previous section.

```
FROM ubuntu:latest
CMD echo -n "Architecture is " && uname -m
```

Build the Docker image using `docker build`. This creates an image for the local machine architecture.

```
docker build -t uname .
```

Run the Docker image using `docker run`.

```
docker run --rm uname
```

The output prints the architecture of the local machine. The previous section explained how to use `docker buildx` to create a multi-architecture image which included the Arm support. This was done using instruction emulation. If the build process is complex, emulation will take too long. A different way to build for the Arm architecture is to use a remote builder. A remote builder provides better performance compared to local `buildx` with emulation. For example, building a large C++ project may have significant slowdown with `buildx`.

Using the same Dockerfile, an image for the Arm architecture can be created from the local machine by using the remote machine. To use the remote machine to build, create a remote context using the `docker context` command. Substitute the `username` and IP address of the remote Arm Linux machine.

```
docker context create remote --docker "host=ssh://username@IP"
docker context use remote
```

As soon as the remote context is set, commands like `docker images` show the images on the remote machine, not the local images. Somewhat mysteriously, all of the Docker commands will be applied to the remote machine. To build an image on the remote machine use `docker build`. Replace `username` with your Docker Hub username.

```
docker build -t username/uname .
```

If you manually use SSH to the remote machine and use `docker images` the results is the same as running `docker images` on the local machine with the remote context set. With the remote context, the run command will also execute on the remote machine.

```
docker run --rm username/uname
```

The output is the architecture of the remote Arm machine. Push the image to Docker Hub. It will go directly from the remote machine to Docker Hub.

```
docker push username/uname
```

To restore the local machine context use the `docker context` command set the context back to `default`.

```
docker context use default
```

A remote context is a powerful concept, but it can be tricky to manage, especially if you forget about it. The next sections cover another way to build multi-architecture images by joining images from different architectures together to form a new multi-architecture image.