Deploy guides

How to deploy a Node.js API on Stackap

To deploy a Node.js API on Stackap you make sure it has a start script and listens on the PORT it is given, set a health path if needed, and push.

Before you start

This guide is for a server that stays running: an API, a small web app, anything that answers HTTP. It is the most flexible path and also the one with the most things that can go wrong, because your own code is in charge of starting correctly.

If your app has its own Dockerfile, Stackap uses it and most of the checks below do not apply.

Check these in your Node.js project

• package.json has a start script that runs the server and does not exit.
• The server listens on process.env.PORT, not a fixed number.
• There is a route that returns a success status when the app is ready, such as /healthz.
• Secrets are read from environment variables, never from files in the repository.
• The app does not write data to its own disk and expect to find it after a deploy.

What to watch while it builds

The first thing to read is the runtime log. A crash on start, a missing variable or a port mismatch shows up there within seconds of the container launching.

An API with no page at the root will fail the default health check. This was reproduced with a toy API and fixed by setting port 8080 and the path /healthz.

When it does not go live

Health check never passes

The app is listening on a hard-coded port, or the health path returns an error. Read the port from PORT and add a health route.

Build refused, no start script

Add a start script, or add a Dockerfile.

Data disappears after a deploy

It was written to the container's disk. Use the project's Postgres database or object storage.

Cannot reach the database

Check the connection string you set. Each project has its own database role that can reach only its own database.

Steps

1. Get access, a token and an SSH key. Request an invitation at the contact page. You receive an API address and a one-time token. Pushing uses SSH, so the public key you push with must also be registered with your organization, which an owner token can do through POST /v1/ssh-keys, or the operator can do for you.
2. Log in and create the project. Log in once, then create a project for the app.

   $ stackap login --url https://api.<your-domain> --token-stdin
   $ stackap create my-api --name "My API"

3. Prepare the repository. Add the project's Stackap remote. If the app serves on a port or health path other than the defaults, the project owner sets them once through the settings API (PUT /v1/projects/:slug/settings), for example port 8080 and /healthz.
4. Set environment variables. Add secrets such as a database URL one at a time from standard input.

   $ stackap env set my-api DATABASE_URL --stdin
   $ stackap env set my-api API_KEY --stdin

5. Push. Deploy and watch the runtime log, since a Node app can build fine and still fail to start.

   $ stackap deploy my-api
   $ stackap logs my-api --source runtime --limit 100

6. Point your domain at it. Create the DNS record, then attach the hostname.

   $ stackap domains add my-api api.example.com

Early-access scope

• The app must serve HTTP; a background worker without a port cannot pass a health check yet.
• No persistent container disk, and no sidecar processes.
• Python and other runtimes are not supported without your own Dockerfile.

Questions

Last updated 2026-10-03.