Skip to content

How-to guides

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.

Updated · Facts checked · By Runtime Cloud

3 min read

Read as Markdown

On Runtime, a Container 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).

Build and push the image

A container host pulls the image from a registry, so the image must be pushed first. With Docker:

Terminaldocker 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).

Locally, docker run -p 8080:80 <image> 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. It uses curl and jq against the API, with your key in RUNTIME_API_KEY.

Terminalapi=https://api.withruntime.com/v2auth="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' EXITpreview=$(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.

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.

Sources

Facts on this page were checked on 17 November 2026.

Cut your cloud billby 66%.

7 days of Pro for $0, and no card to sign up. Billed by the second after.

Start your free trial