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.
Before you begin#
- A program that answers HTTP requests.
- A
Dockerfileat 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:
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
EXPOSE 8080
CMD ["node", "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
CMDorENTRYPOINTstarts 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:
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:
| Size | CPU | Memory |
|---|---|---|
| S | 0.5 vCPU | 512 MiB |
| M | 1 vCPU | 1 GiB |
| L | 2 vCPU | 2 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
/tmpis 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.