Build Configuration

When you deploy from a GitHub repository, Guara Cloud needs to build a container image of your application. There are two available build methods: Dockerfile and Buildpack.

Build methods

Dockerfile

With this method, you provide a Dockerfile in your repository. You have full control over the build environment: base operating system, dependencies, installation commands, and runtime configuration.

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Buildpack

With Buildpack, you do not need a Dockerfile. Guara Cloud automatically detects your application’s language and framework and builds the image for you. Buildpacks support the most common languages and frameworks, including Node.js, Python, Go, Java, and Ruby.

How the method is detected

Guara Cloud automatically detects which method to use:

Situation	Method used
A `Dockerfile` exists in the root directory	Dockerfile
No `Dockerfile` in the root directory	Buildpack

For monorepos, detection considers the root directory configured for the service. If you set /apps/api as the root directory, Guara Cloud looks for apps/api/Dockerfile.

Monorepo

In monorepo repositories, the build uses only the root directory configured for the service. For example, if the root directory is /apps/api, Guara Cloud:

Looks for the Dockerfile at apps/api/Dockerfile
Sets the build context to the apps/api/ directory
Ignores files outside that directory for build purposes

This ensures that each service in a monorepo has independent and efficient builds.

Build caching

Guara Cloud uses layer caching to speed up subsequent builds. When you deploy again, only the layers that changed are rebuilt. This significantly reduces build time in most cases.

To take full advantage of caching with Dockerfile, order your instructions from most stable to least stable:

# Stable layers (change rarely)
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# Dynamic layers (change on every deploy)
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Build environment variables

You can mark specific environment variables as available at build time. These variables are passed as Docker ARG values during image builds, allowing your Dockerfile to use them in build instructions.

Setting build variables

In the dashboard, open the Environment Variables tab of your service and check the Build checkbox next to any variable that should be available during the build. Via the CLI, use the --build flag:

guara env set NPM_TOKEN=abc123 --build

See the environment variables page for more details on managing variables, and the CLI commands reference for the --build flag.

Using build variables in a Dockerfile

Declare the variable with ARG in your Dockerfile, then reference it in build instructions:

FROM node:20-alpine
WORKDIR /app

ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc

COPY package*.json ./
RUN npm ci --only=production
COPY . .

RUN rm -f .npmrc
EXPOSE 3000
CMD ["node", "server.js"]

Common use cases

Private npm tokens — authenticate with private registries during npm install
Registry credentials — pull images or packages from private registries
Build-time configuration — set feature flags, API base URLs, or version strings that are baked into the compiled output