Skip to content

7 ways to use Docker containers on Vercel

Content Engineer

Copy link to headingDocker on Vercel: Seven workflows now supported

Vercel now supports Docker across the platform: container images run as Vercel Functions, Vercel Container Registry stores and serves your images, and Docker runs inside Vercel Sandbox. If you can package an application as an OCI image that serves HTTP, you can deploy it on Vercel with the same git push workflow, preview deployments, and autoscaling as everything else.

Here are seven workflows that support unlocks, with links to the guides and changelog posts for each.

Copy link to heading1. Deploy any HTTP server from a Dockerfile

Add a Dockerfile.vercel (or Containerfile.vercel) to your project that starts an HTTP server listening on $PORT. Vercel detects the file, builds the image on every commit, pushes it to Vercel Container Registry, and serves it from a function on Fluid compute. You get autoscaling without sizing a fleet, and Active CPU pricing means you pay for the compute your code actually uses, not for idle instances.

There's no daemon to run, registry to set up, or cluster to operate. To see the whole flow, follow a Go server with a two-stage build going from Dockerfile to production.

Copy link to heading2. Bring backends written in any language

Framework detection remains the default path on Vercel, and containers are the answer for everything it can't infer: services written in Go, Rust, Python, Ruby, or Java, custom servers, and applications that depend on system libraries such as FFmpeg. A Rails app, a Spring Boot API, a FastAPI service, or a server behind nginx all deploy the same way, because the contract is the image, not the language.

The contract is worth knowing before you write the Dockerfile: Vercel routes traffic to port 80 by default, and you can override it with the PORT environment variable.

Copy link to heading3. Run multiple services in one project

A project no longer has to be one application. Define each backend or frontend as a service in vercel.json, point each service's entrypoint at its Dockerfile path, and route traffic between them with rewrites. Vercel automatically generates environment variables for each service, so services can call each other without hardcoded URLs, and the whole project runs locally with a single command.

This is how a Next.js frontend and a Go API ship from a single repository, project, and domain.

Copy link to heading4. Push and pull images with the Docker tooling you already use

Vercel Container Registry (VCR) is an OCI-compliant registry at vcr.vercel.com that speaks the Docker Registry HTTP API v2. Standard workflows work as-is: docker push, docker pull, docker tag, and docker buildx build --push. That compatibility extends to moving in: images migrate from GitHub Container Registry with the same commands, including multi-platform copies that never pull layers to your machine. You authenticate with OIDC or an access token scoped to the project, repositories are created on the fly when you push, and they're private by default with sharing controls per Vercel team.

When you push an image, VCR optimizes it in the background into a precompiled snapshot, the same format as Sandbox snapshots, so it starts fast on Fluid compute.

Copy link to heading5. Build custom Sandbox images

Vercel Sandbox runs untrusted or agent-generated code in an isolated environment, and VCR images can serve as custom Sandbox base images. Push an image with your toolchain, dependencies, and configuration baked in, and every sandbox that starts from it skips the setup work.

Copy link to heading6. Run Docker inside a Sandbox

Sandboxes also support installing and running Docker itself. An agent can build container images, install system packages, and start containerized services without touching your host system. That makes Sandboxes a natural place to run Redis or Postgres as test dependencies, validate an image before deploying it, or preview an application served from a container. With persistent sandboxes, the Docker installation and pulled images carry over between sessions.

FUSE filesystem drivers and VPN client support shipped alongside Docker, widening what a sandbox can run.

Copy link to heading7. Keep local development and production identical

The reproducibility argument for Docker applies end-to-end on Vercel. vercel dev runs your container image locally, using the Docker CLI and daemon on your machine, so the environment you test is the environment that deploys. To verify a production build without pushing code, build locally and run vercel deploy --prebuilt to upload the generated output directly.

Docker also remains useful for zero-configuration frameworks to pin dependencies across machines; the Next.js repository includes a Dockerfile example for that workflow.

Copy link to headingWhat containers on Vercel are not

Being direct about the boundaries saves you from a failed migration:

  • Containers must be stateless HTTP services. Each instance takes a request, returns a response, and keeps nothing in between. Persistent state belongs in a backing service, such as a database or cache from the Vercel Marketplace.

  • There's no docker compose deployment target. Vercel builds and runs single images. To run several applications together, use services within a single project, not a Compose stack.

  • Instances scale to zero. Functions with no traffic for five minutes in production (30 seconds in preview) scale down. The container receives SIGTERM with a 30-second grace period to clean up.

  • Two networking features aren't supported yet. Secure Compute and Static IPs don't work with custom container images. Everything else behaves like a standard Vercel Function, with the same limits and Active CPU pricing.

Copy link to headingFrequently asked questions

Copy link to headingDoes Vercel support Docker deployments?

Yes. Vercel runs OCI-compatible container images as Vercel Functions. Add a Dockerfile.vercel to your project, and Vercel builds the image, stores it in Vercel Container Registry, and serves it from a function that scales automatically.

Copy link to headingCan I run docker-compose on Vercel?

No. Vercel deploys single container images as HTTP services, not Compose stacks. To deploy several applications together, define them as services in one project and route between them with rewrites in vercel.json. Stateful pieces of a Compose stack, such as databases, belong in external backing services.

Copy link to headingHow are containers priced on Vercel?

The same as other Vercel Functions: Active CPU pricing, so you pay for the CPU time your code uses rather than for provisioned instances. Standard function limits for size, memory, and duration apply.

Copy link to headingWhat happens to my container when traffic stops?

It scales down after five minutes without traffic in production, or 30 seconds in preview. Vercel sends SIGTERM and allows a 30-second grace period for cleanup before terminating the instance. When traffic returns, instances scale back up automatically.

Copy link to headingDo I need to change my Dockerfile to deploy on Vercel?

Usually only the filename. Name it Dockerfile.vercel or Containerfile.vercel, and make sure the server listens on the port in the PORT environment variable, which defaults to 80. The image contents follow standard OCI conventions.

Copy link to headingCan I migrate images from GitHub Container Registry to VCR?

Yes. VCR implements the same Docker Registry HTTP API v2 as GHCR, so images copy over with standard Docker commands, and multi-platform images copy with docker buildx imagetools create without pulling layers locally. Existing gzip-compressed images push without a rebuild.

Copy link to headingRelated resources

More Containers articles

Ready to deploy?

Start deployingTalk to an expert