Deploy a Turborepo monorepo

A Turborepo monorepo deploys to Sevalla as one application per app: each application builds from the same Git repository, and its INGOT_APP environment variable tells Ingot, Sevalla’s builder, which app to build with turbo and start. This guide deploys the web and docs Next.js apps of Turborepo’s starter.

At a glance


Source	A Git repository, deployed as two applications: `storefront-web` and `storefront-docs`
Build	Ingot (Node.js 24, pnpm at the version in `packageManager`) with `INGOT_APP`, or each app’s Dockerfile: `apps/web/Dockerfile`, `apps/docs/Dockerfile`
Start command	`node server.js` from the app’s standalone output, which Ingot sets for Next.js
Port	The `PORT` environment variable, `8080` by default
Processes	One web process per application
Services	None
Disk	None
Size	H1 for each web process

Environment variables

Variable	Required	Available during	Secret	Value
`INGOT_APP`	Yes, with Ingot	Build	No	`apps/web` for `storefront-web`, `apps/docs` for `storefront-docs`
`PORT`	No	Runtime	No	Set by Sevalla to the web process port

Before you begin

A Sevalla company with a payment method, and a GitHub, GitLab or Bitbucket account for the repository. See Git providers.
Node.js 24 or later and pnpm on your computer.

Create the project

Create a monorepo from Turborepo’s basic example:

npx create-turbo@latest storefront --package-manager pnpm
cd storefront

The monorepo is a pnpm workspace with two Next.js apps, apps/web and apps/docs, and shared packages in packages/, such as @repo/ui. Each app’s start script runs next start. create-turbo installs the dependencies and creates a Git repository. The starter pins Next.js 16.3.8, which has security advisories fixed in Next.js 16.4.1. Update both apps to the latest Next.js release:

pnpm up -r --latest next

Prepare the project for Sevalla

Pin the Node.js version in the root package.json:

npm pkg set engines.node="24.x"

The starter sets engines.node to >=24, which lets a new Ingot release move the build to a newer Node.js line. 24.x keeps it on Node.js 24. See Pin the Node.js version. Build each app as a standalone server. Set output in apps/web/next.config.js, and the same in apps/docs/next.config.js:

apps/web/next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
};

export default nextConfig;

With output: "standalone", next build copies the server and only the files it needs from the workspace into the app’s .next/standalone folder. The image runs that server, without the workspace’s other apps or its devDependencies, with Ingot and with a Dockerfile alike. Each Sevalla application builds one app, named by the INGOT_APP environment variable:

Application	`INGOT_APP`
`storefront-web`	`apps/web`
`storefront-docs`	`apps/docs`

With INGOT_APP, Ingot, the default build strategy, builds the app from the repository root, as described in Build an application in a monorepo:

It installs the whole workspace at the root with pnpm install --frozen-lockfile, using the pnpm release in the root’s packageManager field. Commit pnpm-lock.yaml.
Because the repository has a turbo.json, it builds with turbo run build --filter='web...', which builds the web app and the workspace packages it depends on, such as @repo/ui.
It detects the standalone output, copies it into the image and starts the app with node server.js.

The standalone server takes its port from PORT, which Sevalla sets to the web process’s port (8080 by default), so the ports that the dev scripts use don’t matter on Sevalla, and Ingot sets HOSTNAME to 0.0.0.0 so that it listens on all network interfaces. It handles SIGTERM itself: when Sevalla replaces an instance during a deployment, it stops accepting connections and finishes the requests in progress before it exits. Run pnpm build to check that the monorepo builds locally. Then commit everything and push it to your Git provider:

git init
git add .
git commit -m "Prepare for Sevalla"
git branch -M main
git remote add origin https://github.com/acme/storefront.git
git push -u origin main

Deploy to Sevalla

These steps build with Ingot. To build from your own Dockerfiles instead, see Deploy with a Dockerfile.

Create the application

In the sidebar, click Applications, then click Create > Application. Under Source, click Private repository, then choose the Git provider, the Repository and the Branch. Enter storefront-web as the Name. Under Location, choose a Data center. Keep the Size at H1 or choose a larger one, then click Create application. The application opens on its Overview tab with the status Not deployed yet: creating an application doesn’t deploy it.

Add the INGOT_APP variable

Click the Environment variables tab, then click Add environment variables. Enter INGOT_APP as the Key and apps/web as the Value. Keep Available during buildtime selected, because Ingot reads the variable during the build, and click Add environment variables.

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.

Turn on auto-deploy

To deploy every push to the branch automatically, click the Settings tab, then click Update auto-deploy in the Auto-deploy section. Turn on Auto-deploy and click Update auto-deploy. See Deployments.

Deploy the docs app

Repeat steps 1 to 4 for a second application named storefront-docs, from the same repository and branch, with INGOT_APP set to apps/docs.

Verify the deployment

On each application’s Deployments tab, click the deployment. Its Build log shows Ingot’s build plan. For storefront-web, the plan shows apps/web from INGOT_APP, the turbo build of web and the workspace packages it depends on, and the standalone server as the start command:

Build log

╭─ ■ Next.js (standalone) · Node.js 24 ───────────────────────────────────────────────────────────────────────────────────────────────╮
│ App                apps/web                                                                        "app" in ingot.json or INGOT_APP │
│ Node.js            24                                                                              package.json engines "24.x"      │
│ Package manager    pnpm 11.25.0                                                                    package.json packageManager      │
│ Workspace package  web                                                                             apps/web/package.json            │
│ Framework          Next.js (standalone)                                                            apps/web/package.json            │
│ Build              TURBO_TELEMETRY_DISABLED=1 node_modules/.bin/turbo run build --filter='web...'  turbo.json                       │
│ Start              node server.js                                                                  Next.js (standalone)             │
├─ Image ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Build              node:24-trixie                                                                                                   │
│ Runtime            node:24-trixie-slim                                                                                              │
│ User               1000:1000                                                                                                        │
│ Init               tini                                                                                                             │
│ Port               $PORT, default 8080                                                                                              │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Ingot v0.5.0 ─╯

Wait for the deployment’s status to change to Deployed. The application’s status next to its name changes to Running.
Click the domain under each application’s name, for example storefront-web-x7k2m.sevalla.app. Each one opens its own Next.js starter page, which says Get started by editing apps/web/app/page.tsx for storefront-web and apps/docs/app/page.tsx for storefront-docs.

The application header with its name, Running status, repository, branch and the domain that opens the application

To check from a terminal, read the deployment’s status with Get deployment and its build log with Get application deployment logs, as the last steps of Deploy with the API do, then request the domain:

curl -s https://storefront-web-x7k2m.sevalla.app/ | grep -o '<code>apps/web/app/page.tsx</code>'

<code>apps/web/app/page.tsx</code>

If a deployment fails, read its build log, then see Troubleshoot Ingot builds. The error This workspace has several applications and no start script at its root: apps/docs (docs), apps/web (web) means INGOT_APP is missing or isn’t Available during buildtime.

Deploy with a Dockerfile

Ingot needs no Dockerfile. Write your own when you want full control of the image: the base image, the system packages and every layer. Each app gets its own Dockerfile, which uses turbo prune to build only that app and the workspace packages it depends on. Add this one as apps/web/Dockerfile:

apps/web/Dockerfile

FROM node:24-trixie-slim AS prune
WORKDIR /app
RUN npm install -g turbo@2.11.10
COPY . .
RUN turbo prune web --docker

FROM node:24-trixie-slim AS build
WORKDIR /app
RUN corepack enable
COPY --from=prune /app/out/json/ .
RUN pnpm install --frozen-lockfile
COPY --from=prune /app/out/full/ .
RUN pnpm turbo run build --filter=web

FROM node:24-trixie-slim
WORKDIR /app
ENV NODE_ENV=production PORT=8080 HOSTNAME=0.0.0.0
COPY --from=build /app/apps/web/.next/standalone ./
COPY --from=build /app/apps/web/.next/static ./apps/web/.next/static
COPY --from=build /app/apps/web/public ./apps/web/public
RUN mkdir apps/web/.next/cache && chown 1000:1000 apps/web/.next/cache
USER 1000:1000
EXPOSE 8080
CMD ["node", "apps/web/server.js"]

Add apps/docs/Dockerfile with the same content, with docs in place of every web.

Line or choice	Why
`prune` stage	`turbo prune web --docker` writes the `web` app and the workspace packages it depends on to `out/`: their `package.json` files and a pruned `pnpm-lock.yaml` in `out/json/`, and their source in `out/full/`. Install the `turbo` release that the root `package.json` names, 2.11.10 in this starter.
`build` stage	`corepack enable` provides the pnpm release in the root’s `packageManager` field. Installing from `out/json/` before copying `out/full/` lets Docker reuse the installed dependencies when only the code changes.
Final stage	Holds only the standalone server, its static files and `public/`, not the workspace’s other apps, its devDependencies or `turbo`.
`node:24-trixie-slim`	The official Node.js 24 image on Debian 13, the same line that `engines.node` pins for Ingot. The tag follows Node.js 24’s patch releases, so each build gets its security fixes; a digest would stay on one release.
`USER 1000:1000`	The server runs as the image’s unprivileged `node` user. The files stay owned by root, except `.next/cache`, where Next.js writes optimized images.
No init process	The standalone server handles `SIGTERM` itself, so Node.js shuts down cleanly as the container’s first process.
`PORT=8080`, `HOSTNAME=0.0.0.0` and `EXPOSE 8080`	The standalone server listens on `PORT`, which Sevalla sets at runtime, and on the address in `HOSTNAME`. The defaults match Sevalla’s, for running the image on your computer.

Both Dockerfiles share one .dockerignore, at the root of the repository:

.dockerignore

.git
**/node_modules
**/.next
**/.turbo
**/.env*
**/*.log
**/Dockerfile
.dockerignore

Commit and push the three files. Ingot doesn’t use the Dockerfiles, so you can keep them in a repository that builds with Ingot, but it adds the .dockerignore patterns to its own, and its build plan lists them in an Ignored row. Then switch each application to the Dockerfile build strategy:

Choose the Dockerfile build strategy

On the storefront-web application’s Settings tab, in the Build strategy section, click Update build strategy. Click Dockerfile, enter apps/web/Dockerfile as the Dockerfile path, keep the Docker context ., then click Update build strategy. The build needs the whole repository as its context, because turbo prune reads the root’s lock file and every workspace package.

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.

Switch the docs app

Repeat steps 1 and 2 for storefront-docs, with apps/docs/Dockerfile as the Dockerfile path.

The Update build strategy sheet with Dockerfile selected, the Dockerfile path, the Docker context and the Docker registry credential

The storefront-web deployment’s Build log shows 📦 Building and pushing docker image using apps/web/Dockerfile... instead of Ingot’s build plan, and its Dockerfile tab shows your Dockerfile. When the deployments are Deployed, each domain opens its own starter page again. INGOT_APP has no effect on Dockerfile builds, so you can keep it. See Dockerfile for build arguments and private base images.

Deploy changes

With Auto-deploy on, every push to the branch starts a deployment of both applications; otherwise, click Deploy now on each application for each change. Each deployment builds the image, then replaces the web process’s instances. See Deployments.

Deploy only the apps that changed

To deploy an application only when its own files change, set its deploy paths:

Open the deploy paths

Click the application’s Settings tab, then click Update deploy paths.

Allow the app's files

Choose Allow paths and add the files the app is built from, as glob patterns. For storefront-web, add apps/web/**, packages/** and pnpm-lock.yaml. Click Update deploy paths.

Pushes that change none of these files no longer deploy the application. Deploy paths need GitHub or GitLab: Bitbucket pushes don’t list the changed files, so with deploy paths set, every push from a Bitbucket repository is skipped.

Connect the apps to each other

Applications in the same location can reach each other over the private network without going through the internet. On one application’s Networking tab, under Connected services, add an internal connection to the other with Add environment variables to the application turned on: Sevalla adds APP_HOST, the other application’s internal hostname. See Networking.

Add a custom domain

To serve an application from your own domain, such as shop.example.com, add the domain on the application’s Domains tab and create the DNS records that Sevalla shows. Custom domains need a web process larger than H1, so scale the web process first. See Custom domains.

Deploy with the API

The Sevalla API makes the same deployment as Deploy to Sevalla, for both apps, without the dashboard. Run the steps in order in one shell: each step is one API call, and saves the IDs that later steps need in shell variables. Each step also names the CLI command and the MCP server tool that do the same. A variable that holds null means the call failed: run the curl command without its jq part to read the error. You need:

An API key with the Company developer role, or the APP:CREATE, APP:READ and APP:UPDATE permissions, in the SEVALLA_API_KEY environment variable. The CLI reads the key from SEVALLA_API_TOKEN.
The repository on GitHub, GitLab or Bitbucket, and a Git account that can read it connected to your Sevalla user, which only the dashboard can do. See Git providers. Creating the application checks the access: if Sevalla can’t read the repository, the call returns 400 with Cannot access repository https://github.com/acme/storefront: Repository not found or you don't have access., followed by where to grant the access.
curl and jq.

Find the location

List clusters (listClustersV3) returns every location with its id, its name in display_name and its region ID in location. Pick one by its region ID, here eu-frankfurt-1 for Frankfurt, Germany. Locations lists them all.

CLUSTER_ID=$(curl -s https://api.sevalla.com/v3/resources/clusters \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[] | select(.location == "eu-frankfurt-1") | .id')

CLI: sevalla resources clusters. MCP: get_platform_options.

Find the H1 size

The API creates each web process with the S1 size, where the dashboard picks H1. List process resource types (listProcessResourceTypesV3) returns the ID of each size:

H1_ID=$(curl -s https://api.sevalla.com/v3/resources/process-resource-types \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[] | select(.name == "h1") | .id')

CLI: sevalla resources process-types. MCP: get_platform_options.

Choose the app

The next steps deploy one app of the monorepo, named by APP. Run them for web first, then again from this step for docs:

APP=web

Each pass creates one application, storefront-web then storefront-docs.

Create the application

Create application (createApplicationV3) creates storefront-$APP from the repository, with the Ingot build strategy and a web process, and doesn’t deploy it. Both applications use the same repository and branch.

APP_ID=$(curl -s -X POST https://api.sevalla.com/v3/applications \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r .id
{
  "display_name": "storefront-$APP",
  "cluster_id": "$CLUSTER_ID",
  "source": "privateGit",
  "git_type": "github",
  "repo_url": "https://github.com/acme/storefront",
  "default_branch": "main"
}
EOF
)

CLI:

sevalla apps create --name "storefront-$APP" --cluster "$CLUSTER_ID" --source privateGit --git-type github --repository https://github.com/acme/storefront --branch main

. MCP: create_application with deploy set to false.

Find the web process

List processes (listProcessesV3) returns the web process that Create application added:

WEB_ID=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/processes" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.type == "web") | .id')

CLI: sevalla apps processes list --app-id "$APP_ID". MCP: get_application, in processes.

Set the web process size

Update process (updateProcessV3) sets the size, which applies at the first deployment:

curl -s -X PATCH "https://api.sevalla.com/v3/applications/$APP_ID/processes/$WEB_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"resource_type_id\":\"$H1_ID\"}" \
  | jq -r .resource_type_name

h1

CLI: sevalla apps processes update "$WEB_ID" --app-id "$APP_ID" --resource-type "$H1_ID". MCP: scale_process with size_id, and apply_now set to false.

Add the INGOT_APP variable

Create environment variable (createEnvironmentVariableV3) adds INGOT_APP. Ingot reads it during the build to pick the app, so it needs to be available during the build only.

curl -s -X POST "https://api.sevalla.com/v3/applications/$APP_ID/env-vars" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r .key
{
  "key": "INGOT_APP",
  "value": "apps/$APP",
  "is_runtime": false,
  "is_buildtime": true
}
EOF

INGOT_APP

CLI: sevalla apps env-vars create "$APP_ID" --key INGOT_APP --value "apps/$APP", which makes the variable available during both the build and runtime. MCP: set_environment_variables with runtime set to false and buildtime set to true.

Turn on auto-deploy

Update application (updateApplicationV3) with auto_deploy deploys every push to the branch:

curl -s -X PATCH "https://api.sevalla.com/v3/applications/$APP_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_deploy":true}' \
  | jq -r .auto_deploy

true

CLI: sevalla apps update "$APP_ID" --data '{"auto_deploy":true}'. MCP: sevalla_api_update with updateApplicationV3, the application ID as path_params.id and the same body.

Choose the Dockerfile build strategy

Skip this step to build with Ingot. To build from the app’s Dockerfile instead, Update application (updateApplicationV3) sets the build strategy:

curl -s -X PATCH "https://api.sevalla.com/v3/applications/$APP_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"build_type\":\"dockerfile\",\"dockerfile_path\":\"apps/$APP/Dockerfile\",\"docker_context\":\".\"}" \
  | jq -r .build_type

dockerfile

CLI:

sevalla apps update "$APP_ID" --data "{\"build_type\":\"dockerfile\",\"dockerfile_path\":\"apps/$APP/Dockerfile\",\"docker_context\":\".\"}"

. MCP: sevalla_api_update with updateApplicationV3 and the same body.

Deploy

Trigger deployment (triggerDeploymentV3) deploys the latest commit of the branch:

DEPLOYMENT_ID=$(curl -s -X POST "https://api.sevalla.com/v3/applications/$APP_ID/deployments" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  | jq -r .id)

CLI: sevalla apps deployments trigger "$APP_ID". MCP: trigger_deployment.

Wait for the deployment

Get deployment (getDeploymentV3) returns the deployment’s status: waiting, inProgress, then success, failed, cancelled or skipped. Poll it until the deployment ends:

for i in $(seq 1 120); do
  STATUS=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

success

The loop asks every 15 seconds, for up to 30 minutes, and keeps asking through an empty or failed reply. success means the application is deployed. CLI: sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment.

Read the build log

Get application deployment logs (getApplicationDeploymentLogsV3) returns the build log, one line per entry. With Ingot, the App row of the build plan shows the app that INGOT_APP picked, and the Start row the start command:

curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID/logs?limit=5000" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[].message' | grep -E '│ (App|Start) ' | tr -s ' '

│ App apps/web "app" in ingot.json or INGOT_APP │
│ Start node server.js Next.js (standalone) │

With a Dockerfile, the log shows 📦 Building and pushing docker image using apps/web/Dockerfile... (or apps/docs/Dockerfile) in place of the build plan. When a deployment fails, the end of this log says why. CLI: sevalla apps deployments logs "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment_logs.

Check the application

List application domains (listApplicationDomainsV3) returns the application’s domains. Request the application on its domain. Its page names the file to edit, which differs between the two apps:

DOMAIN=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/domains" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.is_primary) | .name')
curl -s "https://$DOMAIN/" | grep -o "<code>apps/$APP/app/page.tsx</code>"

<code>apps/web/app/page.tsx</code>

For docs, the output is <code>apps/docs/app/page.tsx</code>. After the web pass, run the steps again from the step “Choose the app”, with APP=docs.CLI: sevalla apps domains list --app-id "$APP_ID". MCP: get_application, in domains.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

Deploy a Turborepo monorepo

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy with a Dockerfile

Deploy changes

Deploy only the apps that changed

Connect the apps to each other

Add a custom domain

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Create the project

​Prepare the project for Sevalla

​Deploy to Sevalla

​Verify the deployment

​Deploy with a Dockerfile

​Deploy changes

​Deploy only the apps that changed

​Connect the apps to each other

​Add a custom domain

​Deploy with the API

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy with a Dockerfile

Deploy changes

Deploy only the apps that changed

Connect the apps to each other

Add a custom domain

Deploy with the API