Quickstart

Connect GitHub

Open Projects and choose New project. If no GitHub installation is connected yet, Kuppit shows Connect the Kuppit GitHub App. Choose Install on GitHub, pick the account, and grant access to the repository you want to deploy.

You can grant access to a single repository. Kuppit only ever sees what you grant, and you can widen or narrow the grant later from GitHub's application settings or from Settings in Kuppit.

Create a project

Back in New project, choose the repository. Kuppit reads the production branch and analyses it. The Project name is what the project is called in Kuppit, not anything on the repository.

Analyze again is always there. Changing the production branch or the root directory drops the review standing on the page — an analysis describes one branch of one directory, and its inspection is tied to that source — so choose Analyze again to review the new source. Change takes you back to the repository picker and drops the review with it.

For a repository with one application at its root, Kuppit proposes a single web service named web. If the repository uses a Dockerfile, the proposal builds from it. Otherwise Kuppit detects the framework, the Node.js version and the package manager, and builds without one.

Review the proposed architecture

Kuppit draws what it found as the same picture a project's Overview draws: the service as a card, its PostgreSQL as a card, and a line between them carrying the variables the service reads. The services the code depends on that Kuppit will not run — Stripe, Resend, Sentry and the like — stand behind one External services card beside them, counting what detection found; open it to see them and to decide which belong in the project.

The picture is the review. Select a card and its panel opens: a resource's provisioning strategy and name, a service's build settings, an external service's inclusion. The card follows the decision — choose Connect external PostgreSQL and it stops saying Kuppit manages it. Select a line to see the variables it carries. Remove something with Remove from plan and its card and lines go with it.

Nothing is created yet, and the counts above the picture — 2 resources · 1 connection · 1 external service — are what Deploy would create. A resource the analysis would create says so on its own card: Choose how to provision database, in the warning colour, as a control that opens the answer. The panel asks the same question and waits for an answer — the strategy is already selected, since the analysis recommends one, so Create PostgreSQL confirms it, or choose the other and confirm that instead. The footer carries the count — 1 decision needed · Choose how to provision database — and opens the same panel. Deploy project is disabled until every decision is answered, at which point the footer says Ready to deploy and the button turns blue.

Deploy

Choose Deploy project. If the branch has moved since the analysis, Kuppit says so and offers to deploy the analysed commit or analyse the latest one.

The project opens on its Overview: the picture you just reviewed, now the real thing, with the new service and database as cards in the Production box. Open the service's card to watch its first deployment, or the project's Activity tab, which lists every deployment. A deployment moves through four states:

A deployment that stops before reaching production is Failed, and traffic is not moved: whatever was serving before keeps serving. Open the deployment to see which phase failed and the build or runtime logs from it.

For supported frameworks, Kuppit configures the deployment automatically. If you run your own server, it must listen on the port Kuppit assigns and accept connections from outside the container:

const port = Number(process.env.PORT ?? 8080)

server.listen(port, '0.0.0.0')

PORT is set by Kuppit and cannot be overridden. See Web services.

Open the hostname

Every web service gets a stable hostname on kuppit.app when it is created. For a service named web in a project named acme, it looks like acme-a1b2c3.kuppit.app, where the last six characters are unique to the service. Find it on the service's Overview, or on its Domains tab under Kuppit domain.

Open it. Your application is live, with HTTPS.

The database and its connection

A repository that reads DATABASE_URL, or depends on a PostgreSQL client, has a database in its proposal, and accepting the proposal creates the database in the same environment as the service and writes the reference between them:

DATABASE_URL = ${{ database.DATABASE_URL }}

The actual connection string is composed when Kuppit prepares the deployment, from the database's current credentials and address. It is never stored on the service and never shown in the dashboard. Open the database's card to watch it provision; it turns Ready when it can accept connections.

Your application reads the variable like any other environment variable:

import { Client } from 'pg'

const db = new Client({
    connectionString: process.env.DATABASE_URL
})

await db.connect()

If Kuppit did not detect a database — the repository has no PostgreSQL client and reads no connection variable — add one from the environment's Overview under Add resource, then connect it from the service's Variables tab by choosing Reference instead of typing a value. See connections.

Redeploy

Changing variables does not restart anything by itself. The service shows Runtime configuration has changed; choose Redeploy now to build the current commit again with the new configuration. When the deployment reaches Live, the service is connected to the database.