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 and the branch to deploy. Kuppit reads the branch and analyses 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 what Kuppit detected

The proposal shows the build strategy and, for an automatic build, the framework, Node.js version, package manager, build command and start command it found. Change the Root directory if the application lives in a subdirectory of the repository, and Kuppit analyses again from there.

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

Choose Deploy analyzed commit to create the project and its first deployment.

Deploy

The project opens on its Production environment with the new service, and the 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.

Add PostgreSQL

On the environment's Overview, choose Add resource, then PostgreSQL. For a first database there is one choice: Create a new database, which provisions an empty, isolated PostgreSQL database in this environment. Keep the name database, review the plan, and create it.

Provisioning takes a few minutes. The database's card shows its progress and turns Ready when it can accept connections.

Reference the database

Open the web service's Variables tab and choose Add variable. Name it DATABASE_URL, and instead of typing a value, choose Reference and select database → DATABASE_URL. The variable is stored as a reference:

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.

Your application reads it like any other environment variable:

import { Client } from 'pg'

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

await db.connect()

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.