Deploy a Node.js API without managing servers

To deploy a Node.js API without managing a server on blitz.cloud, you put it in a small Docker image that listens on port 8080 and runs as a normal user, push that image to Docker Hub, and pick it in the blitz.cloud dashboard. blitz.cloud runs it in its own sandbox under an HTTPS address and restarts it if the process dies. No VM, no nginx config, no certificates to renew.

The code in this guide is the node-api example. It uses Node's built-in http module so there is nothing to learn beyond Node itself. An Express or Fastify app works the same way.

The server

Two details make a Node app behave well on blitz.cloud. It reads its port from the environment with 8080 as the default, and it stops cleanly when it receives SIGTERM, which is how a container is asked to shut down during a restart.

import http from "node:http";

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

const server = http.createServer((req, res) => {
  if (req.url === "/healthz") {
    res.writeHead(200, { "content-type": "application/json" });
    return res.end(JSON.stringify({ ok: true }));
  }
  res.writeHead(200, { "content-type": "application/json" });
  res.end(JSON.stringify({ hello: "from blitz.cloud" }));
});

server.listen(port, () => console.log(`listening on :${port}`));

process.on("SIGTERM", () => server.close(() => process.exit(0)));

The full version in the repository also talks to PostgreSQL when DATABASE_URL is set. That part is covered in Deploy an app with a PostgreSQL database.

The Dockerfile

# Install dependencies in a throwaway stage so the final image has no npm cache.
FROM node:22.23.2-alpine3.24 AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:22.23.2-alpine3.24
ENV NODE_ENV=production PORT=8080
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY package.json ./
COPY src ./src
# The official Node image ships a "node" user with uid 1000, the same uid
# blitz.cloud runs every app as.
USER node
EXPOSE 8080
CMD ["node", "src/server.js"]

EXPOSE 8080 is not decoration here. blitz.cloud reads the ports an image declares and uses that one, so you don't have to type a port anywhere.

Starting with node directly rather than npm start matters too: npm doesn't pass SIGTERM on reliably, so your shutdown handler would never run.

Test it like blitz.cloud would run it

docker build --platform linux/amd64 -t blitz-example-node-api .
docker run --rm --user 1000:1000 --cap-drop ALL --security-opt no-new-privileges \
  -p 8080:8080 blitz-example-node-api

curl http://localhost:8080/
# {"hello":"from blitz.cloud","database":"none"}

When we ran exactly this, / and /healthz answered 200. If your own app fails at this step, it will fail on blitz.cloud too, and the error is easier to read on your laptop.

Push to Docker Hub

docker build --platform linux/amd64 -t yourname/blitz-example-node-api:1.0.0 -t yourname/blitz-example-node-api:latest .
docker login
docker push --all-tags yourname/blitz-example-node-api

The repository has to be public. Docker Hub is what the wizard searches; a public image on ghcr.io or Quay works too if you type its full name. Tag every build twice, with a version like 1.0.0 and with latest: the version tells you which build is which, and latest is what the Restart route further down relies on.

If you'd rather not push from your laptop, the examples repository has a GitHub Actions workflow that builds for amd64 and pushes on every commit to main, once you add DOCKERHUB_USERNAME and DOCKERHUB_TOKEN as secrets in your fork.

Deploy on blitz.cloud

1. In the dashboard, click Host something new and choose "An app from Docker Hub".
2. Search for yourname/blitz-example-node-api, pick latest and click Continue (the section on shipping new versions below explains why). A repository you just pushed can take a while to show up in Docker Hub's search.
3. What this app needs should say port 8080, "the one the app itself declares".
4. Name it, give it an address such as notes, and click Put it online.

Your API is then at https://notes.yourname.blitz.cloud.

Configuration and secrets

Settings go on the app's Environment tab. Values are stored encrypted, masked on screen, and reach the app the next time it restarts, so change a value, then restart. Up to 64 settings per app.

Shipping a new version

Deploy the latest tag and push a new latest when you release. Automatic updates are on by default for a tag that moves: every night around 4:00 UTC blitz.cloud checks where latest points and puts a newer build online. If the new version doesn't start within ten minutes, the one before comes back. To ship right away, press Restart on the app. A tag named latest is fetched again every time the app starts, so the restart picks up the new build. The tag won't tell you which build is running; the app's Activity tab lists each version that went live.

If your code is on GitHub, you can skip Docker Hub altogether. Connect your GitHub account in blitz.cloud, pick the repository, private ones included, and the branch. Every push then builds the Dockerfile above and puts the new version online. See deploy a GitHub project.

Is this a good fit?

For a small JSON API, a webhook receiver or a Discord bot with an HTTP endpoint, yes. Each app gets 128 MB of memory reserved and up to 512 MB, and a share of a CPU. For a busy API that needs several cores, or for serverless functions that scale to zero and bill per request, it isn't what blitz.cloud does.