# Using Remote Container Builder

The [Remote Container Builder](https://docs.garden.io/features/remote-container-builder) enables you to build container images using **blazing-fast, remote build compute instances** managed by Garden and to share build caches with your team.

Our free-tier includes a certain amount of build minutes and layer caching per month and you get more by switching to our team or enterprise tiers. You can learn more about the [different tiers here](https://app.garden.io/plans).

If you run out of build minutes, Garden will simply fallback to local builds without any disruption.

### Enabling Remote Container Builder

#### Step 1 — Log in to Garden Cloud

You need to be logged into Garden Cloud to use the remote container builder:

```sh
garden login
```

If this is your first time logging in, you'll be asked to sign up.

#### Step 2 — Configure the `container` provider (optional)

The Remote Container Builder is enabled by default once you've logged in, so no further configuration is required.

If you want more granular control and e.g. only enable the container builder in certain environments you can do that via `container` provider in your project level configuration.

For example:

```yaml
kind: Project
name: my-project
environments:
  - name: local
  - name: remote-dev
  - name: ci

providers:
  - name: container # <--- We configure the container builder under the `container` provider
    environments: [remote-dev, ci] # <-- Here we specify what environments in should be enabled in
    gardenContainerBuilder:
      enabled: true
  - name: kubernetes
    # ...
```

#### Step 3 — Give it a spin (optional)

If you a already have a Garden project with `container` Build actions, simply run:

```
garden build
```

...or any other command that triggers a build.

If you're using the `kubernetes` provider, the image will be pushed to the configured `deploymentRegistry`.

You can then check out the results in the [new Builds UI](https://app.garden.io).

### Known Limitations

#### Base images from other Build actions require a remote registry

When one Build action uses another Build action's output as a base image (via a `FROM` instruction referencing a build arg), a remote container registry must be configured for the Remote Container Builder to work.

For example, given a config like this:

```yaml
kind: Build
type: container
name: main
dependencies: [build.base]
spec:
  dockerfile: main.Dockerfile
  buildArgs:
    BASE_IMAGE: ${actions.build.base.outputs.deploymentImageId}
```

Where `main.Dockerfile` contains:

```dockerfile
ARG BASE_IMAGE
FROM $BASE_IMAGE
```

The Remote Container Builder will build the `base` image remotely and download it to your local Docker daemon. However, when it then builds `main`, the remote builder cannot resolve the `base` image because it only exists locally—not in any registry the remote builder can pull from.

Without a registry, the build will fail with an error like:

```
failed to resolve source metadata for docker.io/library/base:v-<hash>: not found
```

**Workaround:** Configure a `deploymentRegistry` in your `kubernetes` provider so that built images are pushed to a registry that the remote builder can access. Alternatively, you can disable the Remote Container Builder for environments that use this pattern.

### Next steps

If you haven't already, check out our docs on [building containers](https://docs.garden.io/using-garden-with/containers/building-containers) to learn how to add `container` Build actions to your project. Note that the Remote Container Builder also supports [multi-platform builds](https://docs.garden.io/using-garden-with/building-containers#doing-multi-platform-builds)!

Your `container` actions will be built by the container builder and can be used by other actions, e.g. to:

* [Deploy K8s resources](https://docs.garden.io/using-garden-with/kubernetes/deploy-k8s-resource)
* [Install Helm charts](https://docs.garden.io/using-garden-with/kubernetes/install-helm-chart)
* [Run tests](https://docs.garden.io/using-garden-with/kubernetes/run-tests-and-tasks)