Migrating from Docker to Machine

1 week ago1 min read
Last updated • Read time
Cloud
This document is applicable to CircleCI Cloud
Server v4+
This document is applicable to CircleCI Server v4+

This page contains some general guidelines and considerations to make when moving from the Docker executor to machine, or vice versa.

Overview

In some situations, the Docker executor is not the right fit for your builds, for example if using a Docker resource class is providing a lack of memory or if there is a requirement for more dedicated CPU power. Moving to a dedicated virtual machine can help alleviate these issues. However, changing out an executor is not as simple as replacing a few lines of configuration. You will also need to consider the tools and libraries required to be installed for your application and tests.

Pre-installed software

The most up to date list of pre-installed software can be found on the image builder page. You can also visit the CircleCI community forum for more information.

Additional packages can be installed with sudo apt-get install <package>. If the package in question is not found, sudo apt-get update may be required before installing it.

Running Docker containers on machine

Machine executors come installed with Docker, which can be used to run your application within a container rather than installing additional dependencies. We recommend using a custom Docker image rather than a CircleCI convenience image, which are built under the assumption they will be used with the Docker executor and may be tricky to work around. Since each machine executor environment is a dedicated virtual machine, commands to run background containers can be used as normal.

If you have Docker Layer Caching (DLC) enabled for your account, machine executors can utilize this to cache your image layers for subsequent runs.

Why use Docker executors at all?

Machine executors offer double the memory and a more isolated environment for running builds, but there is additional overhead regarding spin up time, and, depending on the approach taken for running the application, more time taken to install the required dependencies or pull your Docker image. The Docker executor will also cache as many layers as possible from your image during spin-up, as opposed to the machine executor, where DLC will need to be enabled.

All executors have their pros and cons, which have been laid out here to help decide which is right for your pipelines.

Further reading

We have more details on each specific executor here, which includes links to specific memory and vCPU allocation details, as well as how to implement each one in your own configuration.