Build with a Dockerfile

If you have a single repository with multiple services, or your repository is structured so that your Dockerfile is not in the root, you can specify its location when creating or editing your services.

You can specify the location of the Dockerfile relative to the root of the repository. For example root: /Dockerfile, or in a subdirectory: /directory/subdirectory/Dockerfile.

You can use a Dockerfile outside the build context, but commands in your Dockerfile are relative to the build context. If your build context is set to /app/src, the Docker command COPY . /src will copy all files from /app/src to the /src directory in your container.

Learn more about the Dockerfile .

BuildKit is the default and recommended build engine. Select it under Build engine in Advanced build settings to use disk caching.

You should always include a .dockerignore file in your repository, in order to reduce the final image size by excluding everything unnecessary.

For example to ignore the git folder and .env files you would add the following to .dockerignore:

.git
*.env

Northflank provides built-in build caching only for Dockerfile builds with BuildKit. With disk caching enabled, BuildKit stores build data on persistent disk so later builds can reuse steps with unchanged instructions and inputs.

Each service or job has its own independent cache. An empty cache needs a successful build to populate it.

Enable build caching

Disk caching must be available for your team. Bring Your Own Cloud (BYOC) build clusters also need storage that supports build caching. If the control is unavailable with BuildKit selected, contact Northflank support.

To enable disk caching:

1. Open the build configuration for a service or job that builds from a Dockerfile.
2. Expand Advanced build settings.
3. Select BuildKit under Build engine.
4. Enable Use disk cache (cache image layers on local disk).
5. Select a capacity under Disk-based cache storage.
6. Save the configuration.

The interface shows capacity in GB. This capacity covers both cached build data and scratch space for the current build. Cache cleanup targets approximately 60% of the disk capacity. Select enough storage for both cached data and the current build. You can increase capacity later in the build configuration. Treat the cache as reusable build data, not permanent storage for application data.

Configure caching with the API or templates

Use this fragment in a service or job create, PUT, or PATCH request. In a resource template node, these fields belong inside spec:

{
  "buildSettings": {
    "dockerfile": {
      "buildEngine": "buildkit",
      "buildkit": {
        "useCache": true,
        "cacheStorageSize": 16384
      }
    }
  }
}

In API create requests, useCache defaults to false. When you enable it, include cacheStorageSize. The API specifies this capacity in MB, so the example requests 16384 MB. Include the other required fields for your request or template node.

Improve cache reuse

Copy dependency files before application source files. This lets source changes reuse the dependency installation step.

This Node.js build stage requires a build script in package.json. It also requires a committed package-lock.json that matches package.json:

# syntax=docker/dockerfile:1
FROM node:lts-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

Changes to application source can reuse the npm ci layer. Changes to package.json or package-lock.json rebuild the dependency layer and the steps after it.

Exclude node_modules and other unnecessary files with a .dockerignore file. This keeps local dependencies out of the build and reduces changes to its inputs.

A cache mount is a reusable directory for dependencies. To reuse downloaded npm packages when the installation step runs again, replace RUN npm ci with:

RUN --mount=type=cache,target=/root/.npm npm ci

This mount caches package downloads. It does not prevent npm ci from running when the layer needs rebuilding. Other package managers use different cache directories. See Docker's cache mount guidance .

Clear the build cache

The Clear build cache action appears for BuildKit builds with disk caching enabled. It clears the service or job's cache across all build clusters. It does not delete built images or stop running builds. If any builds are active, they will finish, but their cache data is discarded when they complete.

To clear the cache before a new build:

1. Open the service or job's Builds page.
2. Select Clear build cache.
3. Wait for the Build cache cleared message.
4. Start a new build to populate the cache again.

Troubleshoot build caching

If your Dockerfile contains multiple build stages you can specify the target stage by entering its name here.

For example, for a Dockerfile with the following stages:

FROM debian AS build-env
# ...

FROM alpine AS production-env
# ...

Specifying the target stage as build-env will build an image using the commands up until, but not including the production-env stage.

Learn more in the Docker documentation .

You can access private images from external container registries in your Docker build process by applying the relevant registry credentials in the build settings. You can add or update build credentials for any resource that builds from a Git repository and uses a Dockerfile, under the advanced build setting section in build options.

You can use multiple container registries, but only one credential per container registry can be selected.

After applying the credentials you can use private images in the Dockerfile for the build, in the format FROM <container-registry>/<account>/<image>:<tag>.

When you build an image Northflank performs a shallow clone of your git repository by default, as only the most recent commit is required in the build process. The .git folder is also excluded by default.

If you require the .git folder in your build, you can include it in the build environment by selecting include .git folder in the build options section of a service or job, under advanced build settings.

If you require the entire git history to be available, you can also enable full clone. This may significantly increase the time it takes to build larger repositories with extensive histories.