Deploy a Node.js API from GitHub

Before you start

• Your API should be in a GitHub or GitLab repository.
• Commit your lockfile, such as bun.lock, package-lock.json, or pnpm-lock.yaml.
• Your server must listen on the PORT environment variable Shiprr provides.

Recommended Shiprr settings

Shiprr can usually detect a Node.js app from package.json. For a Bun-based API, use these settings under App → Settings → Build & Runtime.

root directory: ./
install command: bun install
build command: bun run build
start command: bun run start
health check path: /health

If your API does not need a compile step, leave the build command empty or set it to the same command you use in CI. Replace bun with npm or pnpm if that is what your project uses.

Listen on PORT

Your app should bind to process.env.PORT. A simple Express server looks like this:

const port = Number(process.env.PORT || 3000);

app.get("/health", (_req, res) => {
  res.status(200).send("ok");
});

app.listen(port, "0.0.0.0", () => {
  console.log("API listening on " + port);
});

Binding to 0.0.0.0 makes the app reachable inside the runtime environment. Binding only to localhost can make health checks fail.

Environment variables

Add production config under App → Settings → Environment variables. Running apps are redeployed so new values apply to live replicas.

DATABASE_URL=postgres://...
REDIS_URL=redis://...
JWT_SECRET=change-me
NODE_ENV=production

Keep secrets out of Git and avoid printing secret values from your app. Anything written to stdout or stderr can appear in runtime logs.

Deploy

1. Open the dashboard and choose Apps → New app.
2. Connect GitHub or GitLab if needed.
3. Select the repository, branch, region, root directory, and deploy trigger.
4. Confirm install, build, start command, health check path, and env vars.
5. Create and deploy the app.

New apps start with 1,000 MHz CPU and 512 MB RAM per replica. Increase CPU, RAM, or replicas if the API is CPU-bound, memory-heavy, or needs more request capacity.

Verify and debug

• Use build logs when dependency install, TypeScript compile, or bundling fails.
• Use runtime logs when the API starts and then crashes or cannot connect to services.
• Use the health check path to make startup problems visible before traffic is sent.

After the default Shiprr hostname works, attach a custom domain from the app's Domains page. Shiprr provisions HTTPS automatically after DNS points to the Shiprr target.

Rollback

If a release breaks the API, roll back from deployment/build history. Shiprr reuses the selected previous successful build, skips a source rebuild, and creates a fresh deployment attempt with current runtime settings.