Builds
Every deployment starts with a build: the commit becomes a container image, one of two ways. Kuppit decides which when the service is created, from what is in the repository, and records the result as the service's build configuration. You can change any of it on the service's Settings tab.
Dockerfile or Automatic
| Strategy | Kuppit chooses it when | What it does |
|---|---|---|
| Dockerfile | A Dockerfile exists in the root directory. Recommended whenever one is present. | Builds the Dockerfile exactly as written, with a layer cache kept per service between builds. |
| Automatic | No Dockerfile, and a Node.js application is detected. | Installs dependencies, runs the build command if there is one, and starts the start command. |
Detection reads the repository; it never guesses. If neither applies, the service's settings say Automatic configuration not detected: add a Dockerfile, or set the framework and commands by hand.
What Automatic detects
An automatic build supports Node.js applications only.
- Framework: Nuxt, Next.js, Express, or plain Node with a
startscript. - Node.js version: 24 or 22. Kuppit reads
engines.nodeinpackage.json, or.nvmrc, and defaults to 24. The range must admit the current release of that major. - Package manager: pnpm, npm or Yarn, from the lockfile or the
packageManagerfield. Two lockfiles, or apackageManagerthat disagrees with the lockfile, is an error. Yarn Classic is recognised from its lockfile; Yarn Modern needs an exactpackageManagerversion. - Build command:
pnpm build,npm run buildoryarn buildwhenpackage.jsonhas abuildscript; none otherwise. - Start command: for Nuxt,
node .output/server/index.mjs; for Next.js without astartscript,next start; otherwise the package manager'sstart. - Port: 3000 when detected, and the runtime tells your server the real port through
PORT.
Workspaces are understood: an application inside a pnpm, npm or Yarn workspace builds from the workspace root with the application as its root directory.
Settings
Each setting is what Kuppit detected until you change it, and only the values you change are stored. Saving shows Build settings saved. Changes apply to the next deployment.
| Setting | Applies to | Notes |
|---|---|---|
| Root directory | Both | Where the application lives in the repository. Changing it needs a fresh inspection before you can save. |
| Dockerfile path | Dockerfile | Relative to the root directory. |
| Framework | Automatic | Nuxt, Next.js, Express or Node. |
| Node version | Automatic | 24 or 22. |
| Package manager and version | Automatic | pnpm, npm or Yarn. |
| Build command | Automatic | Optional. Clearing it removes a detected build step. |
| Start command | Automatic | Required. |
| Port | Automatic | 1 to 65535. A Dockerfile build always listens on 8080. |
Commands run as POSIX shell scripts inside the isolated build or runtime environment, and are limited to 4 KB. Do not put secrets in them; use variables.
Inspect latest re-detects from the newest commit and shows what changed before you save it. Kuppit never re-detects on its own: automatic defaults stay fixed until you explicitly inspect and save, so a commit that adds a Dockerfile does not silently change how the service builds.
What the deployment keeps
Each deployment snapshots the build configuration it was resolved with and shows it read-only under Build configuration on the deployment page, with the commit it inspected. Changing settings afterwards changes the next deployment, never this one.
Limits
- A repository is read up to 20,000 files, and extraction stops after 60 seconds. Beyond that the build fails with The repository is too large for Kuppit to build.
- A build has 15 minutes to produce an image. Beyond that it fails with The build ran out of time.
- Symbolic links are never followed, and
node_modules,.git, build output directories and caches are never walked during detection.