Monorepo guide

# How do I deploy a monorepo to Cloud Noce?

Learn to deploy several services from one repository in Cloud Noce. Configure the root directory, Dockerfile path, build context and watched paths, then deploy with the CLI.

Short answer

For each application in your monorepo, such as `apps/web`, `apps/api` and a worker, create a **separate service** on [Cloud Noce PaaS](/en/products/paas) . All services can connect to the same repository and branch. The root directory determines where each service is detected and built; watched paths prevent unnecessary deployments of other services.

Last reviewed:6 September 2026

## How monorepos work in Cloud Noce

One repository can contain several Cloud Noce services. Each service has its own build and start commands, variables, domain, replica count and releases, while sharing a project and environment with the others.

```
repo/
├── apps/
│   ├── web/       # web service
│   └── api/       # API service
├── packages/
│   └── shared/    # shared package
├── package.json
└── pnpm-lock.yaml
```

## Configure the three build fields

- **Root directory:** The service folder's path relative to the repository root. For the API, use `apps/api`. Stack detection and build and start commands run from this folder.

- **Dockerfile path:** The file's path relative to the repository root, for example `apps/api/Dockerfile`. An explicit Dockerfile always takes precedence over automatic detection.

- **Build context:** Applies only to Dockerfile builds. Set it to `.` to make the root lockfile and shared packages accessible to `COPY` . If left empty, it defaults to the root directory.

## Recommended setup for workspaces with shared packages

If an application needs a lockfile or packages outside its own folder, keep the Dockerfile in the application folder and set the build context to the repository root.

```
# Build configuration fields in the Cloud Noce panel
Root directory:  apps/api
Dockerfile path: apps/api/Dockerfile
Build context:   .
Watched paths:
  apps/api/**
  packages/shared/**
  pnpm-lock.yaml
```

In a Dockerfile, `COPY` paths are relative to the build context. Without a Dockerfile, Cloud Noce runs Nixpacks or its built-in stack builder in the root directory and ignores a custom build context. Projects that depend on repository-root files therefore usually need a Dockerfile with the repository root as their build context.

## Watched paths and automatic deployment

For Git-connected services, a push to the connected branch rebuilds a service only if a changed file matches its watched paths. An empty list means every push triggers a deployment.

- `apps/api` matches all files under this path.

- `apps/api/**` matches files at any depth below apps/api.

- `apps/*` matches one path segment, without including deeply nested files.

- Add separate patterns for the lockfile, root configuration and shared packages.

- If GitHub cannot provide a reliable file list for a very large push, Cloud Noce rebuilds the service to avoid missing an update.

## Configure and deploy with Gerdoo CLI

For local source code, the CLI packages the supplied repository and detects the stack in the directory specified by `--root-dir` :

```
cd repo
gerdoo deploy . \
  --name api \
  --root-dir apps/api \
  --dockerfile apps/api/Dockerfile \
  --build-context . \
  --port 8080
```

For an existing Git-connected service, update its monorepo settings and watched paths:

```
gerdoo service update api \
  --root-dir apps/api \
  --dockerfile apps/api/Dockerfile \
  --build-context . \
  --watch-path 'apps/api/**' \
  --watch-path 'packages/shared/**' \
  --watch-path pnpm-lock.yaml
```

## Deployment checklist

- Set a separate root directory and health check path for each service.

- Add shared packages and lockfiles to the watched paths of every service that uses them.

- Set shared variables at project or environment level, and service-specific secrets on the service.

- Change only the web application and confirm the API is not rebuilt unnecessarily.

- Change a shared package and confirm all services that use it are deployed.

- Check the build log to confirm the expected builder, Dockerfile and build context were selected.

- Roll back each service separately and test communication between services.

## Frequently asked questions

### Do I need a service for each application in a monorepo?

Yes. In Cloud Noce, each web application, API, worker or scheduled job is a service. Connect each service to the same repository and branch, with its own root directory and watched paths.

### What is the difference between the root directory and build context?

The root directory is the service's own folder, used for stack detection and build commands. The build context applies only to Dockerfile builds and determines which repository files COPY can access.

### What is the Dockerfile path relative to?

It is relative to the repository root, not the service's root directory or build context. For example: apps/api/Dockerfile.

### Which patterns do watched paths support?

A simple path such as apps/api matches as a prefix. * matches within one path segment, ** spans directories and ? matches one character. Add packages/** to include shared packages.