Web services
A web service is an application built from your repository and deployed on a public hostname. It is the resource that has deployments, logs, variables and domains.
Every project starts with one, named web, proposed from the repository when the project is created. An environment can hold more than one web service, for example an API next to a frontend, and each has its own hostname and its own deployments.
Adding a web service
On an environment's Overview, choose Add resource, then Web service. Kuppit analyses the branch the environment deploys and proposes what to build, so a second service can point at a different Root directory of the same repository.
A service can be added to Production or a custom environment. A preview environment's services are copied from Production when the pull request opens and are removed when it closes, so nothing can be added to one by hand.
How a service is built
Kuppit builds a container image for every deployment, one of two ways.
| Strategy | When Kuppit chooses it | What it needs |
|---|---|---|
| Dockerfile | A Dockerfile exists in the root directory. | The Dockerfile, and whatever it copies. |
| Automatic | No Dockerfile, and a Node.js application is detected. | A package.json with a recognised framework or a start script. |
An automatic build supports:
- Frameworks: Nuxt, Next.js, Express, or plain Node.js with a
startscript. - Node.js: 24 or 22. Kuppit reads the version from
package.jsonenginesor.nvmrcand defaults to 24. - Package managers: pnpm, npm or Yarn, from the lockfile or the
packageManagerfield.
Kuppit records what it detected as the service's Build configuration: root directory, framework, Node.js version, package manager, build command, start command and port. Each can be overridden on the service's Settings tab. Clearing the build command removes a detected build step.
When a later commit changes the shape of the repository, for example by adding a Dockerfile, Kuppit says so and asks you to inspect the latest commit before saving new settings.
The PORT contract
Kuppit starts your container with PORT set and routes traffic to that port. Your server must listen on it, on all interfaces:
const port = Number(process.env.PORT ?? 8080)
server.listen(port, '0.0.0.0')
Nuxt and Next.js read PORT themselves. Express and plain Node.js applications must read it as above. A server bound to localhost or to a hard-coded port does not receive traffic, and the deployment fails its health check.
PORT, K_SERVICE, K_REVISION and K_CONFIGURATION are set by the runtime and cannot be used as variable names.
Deployments
A deployment is one commit becoming one running revision of the service. Kuppit creates one:
- when you push to the branch the environment deploys,
- when you choose Deploy on the service,
- when you Redeploy a commit or Roll back to a previous deployment.
A new revision takes traffic only after it passes a health check. Until then the previous revision keeps serving, so a failed deployment never takes the service down. The service's Deployments tab lists the Live deployment, its history, and the Build and Runtime logs of each.
Service health
Service health describes whether the currently deployed service is serving successfully. It is separate from deployment status, which describes the lifecycle of an individual deployment: an environment can show a deployment Building while the service inside it is still Healthy, because the previous revision is still up.
| Health | Meaning |
|---|---|
| Healthy | Serving production traffic. |
| Starting | Reaching production for the first time. |
| Failed | Nothing has reached production. |
| Not deployed | Nothing has been deployed yet. |
Hostnames and domains
Every web service receives a stable hostname on kuppit.app when it is created, of the form <project>-<service>-<id>.kuppit.app. A service named web drops the service part, so a project named acme gets acme-a1b2c3.kuppit.app. A preview environment prefixes its name: pr-42-acme-a1b2c3.kuppit.app.
Custom domains are attached on the service's Domains tab. A subdomain takes a CNAME to domains.kuppit.app; an apex domain takes an ALIAS or ANAME record. Kuppit verifies ownership with a TXT record and issues the certificate.
Variables
A web service has its own variables, and inherits every variable set on its environment. Values can be literals or references to variables another resource exposes, such as a database's DATABASE_URL. See Environment variables.
A web service does not expose any variables of its own for other resources to reference.