# How to deploy a Docker container Build the image, push it to a registry, and ask a container host to run it with the port it listens on routed to an HTTPS address. **On Runtime, a [Container](/docs/containers) runs one OCI image from any registry, under Docker on a Linux machine of its own, and serves the port it listens on through a preview. It pauses after five minutes with nothing to do, and the next request resumes it.** Name the image in the `RUNTIME_CONTAINER_IMAGE` environment variable. Each container is its own Firecracker microVM, so two containers never share a kernel ([microVM vs container](/compare/microvm-vs-container)). ## Build and push the image A container host pulls the image from a registry, so the image must be pushed first. With Docker: ```bash no-run docker build -t ghcr.io/acme/web:1.4.2 . docker push ghcr.io/acme/web:1.4.2 ``` The image needs three things to run well on any host: | Need | In the Dockerfile | | --- | --- | | A port to route to | The server listens on `0.0.0.0` and a known port. `EXPOSE` documents it but publishes nothing | | A command that starts it | `CMD` or `ENTRYPOINT`, in the exec form (`["node", "server.js"]`) so it receives `SIGTERM` | | The right CPU type | Build for `linux/amd64`, or for both with `docker buildx build --platform linux/amd64,linux/arm64` | Tag each build with a version, never only `latest`. A host that pulls `latest` tomorrow may get a different image than you tested. To pin an exact build, use its digest, `ghcr.io/acme/web@sha256:...` ([what an OCI image is](/glossary/oci-image)). Locally, `docker run -p 8080:80 ` maps a port on your machine to the port inside the container. A host does the same mapping for you, to an HTTPS address. ## Run it on Runtime This script runs the public image `traefik/whoami`, which listens on port 80, and reads it through a [preview](/glossary/preview-url). It uses `curl` and `jq` against the [API](/docs/reference/containers), with your key in `RUNTIME_API_KEY`. ```bash check api=https://api.withruntime.com/v2 auth="Authorization: Bearer $RUNTIME_API_KEY" # The image to run, from any registry. traefik/whoami listens on port 80. container=$(curl -sf -X POST "$api/containers" -H "$auth" -H "Content-Type: application/json" \ -d '{"env": {"RUNTIME_CONTAINER_IMAGE": "traefik/whoami"}}' | jq -r .id) trap 'curl -sf -X DELETE "$api/containers/$container" -H "$auth" > /dev/null' EXIT preview=$(curl -sf -X POST "$api/sandboxes/$container/previews" -H "$auth" \ -H "Content-Type: application/json" -d '{"port": 80}') url=$(jq -r .url <<< "$preview") token=$(jq -r .token <<< "$preview") # The first request waits while the image is pulled. curl -sf --retry 60 --retry-all-errors --retry-delay 1 "$url" -H "x-runtime-preview-token: $token" | head -n 1 # Hostname: ... ``` The `trap` deletes the container when the script ends. Leave it out to keep it. Share the port your own image listens on, which is not always 80. With no `RUNTIME_CONTAINER_IMAGE`, a Container runs `nginx:stable`. ## Container or whole machine A Container runs your image as it is, as one process tree under Docker. To boot the whole machine from your own image instead, with your packages in every sandbox, app or function that starts from it, build a [Runtime image from a Dockerfile](/how-to/build-an-image-from-a-dockerfile). ## Mistakes to avoid - **Listening on `127.0.0.1`.** The server answers inside the container and nowhere else. Listen on `0.0.0.0`. - **The shell form of `CMD`.** `CMD node server.js` runs under `/bin/sh -c`, which does not pass `SIGTERM` on, so a stop waits for its timeout and then kills the process. - **An image built only for Arm.** An image built on an Apple silicon Mac is `linux/arm64` unless you say otherwise. An `amd64` host cannot run it without emulation. - **Secrets baked into a layer.** A key copied in and deleted in a later step is still in the earlier layer. Pass it as an environment variable at run time. ## Related - [What is an OCI image?](/glossary/oci-image) - [What is a container?](/glossary/container) - [How to deploy a Node.js app](/how-to/deploy-a-nodejs-app), from source without an image - [What is a platform as a service (PaaS)?](/glossary/platform-as-a-service) ## Sources - [Docker Docs, Dockerfile reference](https://docs.docker.com/reference/dockerfile/), checked 17 November 2026 - [Docker Docs, docker container run](https://docs.docker.com/reference/cli/docker/container/run/), checked 17 November 2026 Facts on this page were checked on 17 November 2026.