Crescendo Lab Docs
English
Sign up

Deploy a web service from a Dockerfile

Deploy a long-running service, such as a webhook, an API or a tool for agents, from source code with a Dockerfile.

Last updated

Before you begin#

  • A program that answers HTTP requests.
  • A Dockerfile at the top of the project.

1. Write the Dockerfile#

This Node.js example listens on $PORT, exposes exactly one port, and runs as a non-root user:

Dockerfile
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
EXPOSE 8080
CMD ["node", "server.js"]
server.js
import { createServer } from "node:http";

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

createServer((req, res) => {
  res.writeHead(200, { "content-type": "application/json" });
  res.end(JSON.stringify({ ok: true, path: req.url }));
}).listen(port);

The image must meet these rules. The container runtime contract has the full list.

  • A CMD or ENTRYPOINT starts the server.
  • The server answers HTTP on $PORT.
  • The image is built for linux/amd64.
  • The filesystem is read-only apart from /tmp, which has its own limits.

2. Upload the source#

On the project's Deploy tab, drop the source folder or its .zip on the upload area, then select Upload and build. The Dockerfile must be at the top. If you make the zip yourself, leave out node_modules, .git and .env:

bash
zip -r ../app.zip . -x 'node_modules/*' '.git/*' '.env*'

The platform builds the image, scans it for vulnerabilities and secrets, and checks it against the runtime contract. Anything the platform adapted shows as a notice on the version page, for example "The image runs as root, so it runs as uid 10001."

3. Go live and check the runtime#

A project's first version goes live on its own once it builds. Later versions go live when you select Go live on the Deploy tab.

The Runtime tab shows which version is serving and how many instances are ready.

The version never becomes ready

The usual cause is the port: the server isn't listening on the port the platform gave it. See Troubleshoot failed deployments.

4. Add secrets#

Enter API keys and other secret values in the project's Settings. Your code reads them as environment variables. While the service is running, saving restarts it in one confirmed step, and the old instances keep serving until the new ones are ready. See Project settings.

Keep secrets out of your source

If the scan finds a key in the image, take it out of the source, set it as a secret of the project instead, and rotate the key.

Limits#

Memory and CPU

Every instance runs at the project's size, the Size setting in the project's Settings:

SizeCPUMemory
S0.5 vCPU512 MiB
M1 vCPU1 GiB
L2 vCPU2 GiB

Memory is a hard limit. An instance that needs more is stopped and starts again. If you raise Node.js's heap with --max-old-space-size, keep it below three quarters of the memory: the rest of the process needs some too. The build notes on the version page warn when it is higher.

Files in /tmp

/tmp is the only place your code can write to.

  • It holds up to 256 MiB. The files are on disk and do not count toward the memory above.
  • It starts empty every time the instance restarts and every time a new version goes live. Each instance has its own.
  • Writing more than 256 MiB stops the instance. A new one replaces it, and its /tmp is empty.

Use it for caches and temporary files, not for data that has to last.

Don't run a database in the container

A database server started inside the image, such as PostgreSQL, MySQL, MongoDB or Redis, keeps its data inside the instance. That data is lost whenever the instance restarts or a new version goes live, and it takes memory from your own server. The build notes warn when the Dockerfile installs or starts one.

Keep data in an Agent Lab database (PostgreSQL or MySQL) or a Redis cache instead. Your code connects to it through environment variables.