Skip to content

Overview

Clever Cloud builds an image from the Dockerfile of your project and runs it as a container. Each instance is a virtual machine with its own Docker daemon, running one application container, which isolates it from other applications. Use Docker for a language or system libraries no other runtime provides, or to deploy an application you already ship as an image, built in your own CI for instance.

What’s different with the Docker runtime

Other runtimes run your application in an environment Clever Cloud prepares and maintains: an image with the language, its tools and their versions, and services in front of your application. With Docker, Clever Cloud manages the operating system of the virtual machine and the Docker daemon, then builds and runs your image. What happens inside the container is up to you:

  • The base image, and thus the operating system of the container, its packages, and their versions
  • The tools and package managers of the image, such as Mise: Clever Cloud doesn’t install or run any in the container
  • The ports the container listens on, and the processes that answer on them
  • The updates of all of this: change the base image or the versions in your Dockerfile, then deploy again

Thus, features that rely on the application environment of other runtimes don’t apply to Docker applications:

  • Workers: start your background processes from your image
  • CRON jobs of a clevercloud/cron.json file: run a scheduler within your container
  • Request Flow middleware, such as Varnish or Redirection.io: run them in your container
  • Deployment hooks, except CC_RUN_SUCCEEDED_HOOK, which runs inside the container: put the build steps in your Dockerfile

Docker applications don’t support FS Buckets and Docker Compose: each instance runs one application container. For several containers working together or persistent volumes, use Clever Kubernetes Engine, and manage your add-ons with the Clever Kubernetes Operator.

Create your Docker application

To create a new Docker application, use the Clever Cloud Console or Clever Tools:

clever create --type docker

Configure your Docker application

Mandatory needs

A Docker application needs:

  • A Dockerfile at the root of the project
  • A web server listening on 0.0.0.0:8080 in the container
  • A command that starts your application, set with CMD or ENTRYPOINT in your Dockerfile or in its base image

To use another file, set its path in CC_DOCKERFILE, such as docker/Dockerfile.prod. With CC_APP_FOLDER, Clever Cloud looks for the Dockerfile in this folder. To listen on another port, set it in CC_DOCKER_EXPOSED_HTTP_PORT. A Clever Task doesn’t need a web server.

In most cases, CMD gives the whole command, such as CMD ["node", "server.js"]. If the image sets an ENTRYPOINT, it’s the program to run, and CMD only gives its arguments, as in the following example. Learn more in the Docker documentation.

For instance, this Dockerfile serves a small language model on CPU with llama.cpp, with a chat interface and an OpenAI-compatible API. Its image sets llama-server as ENTRYPOINT: the CMD gives the model and the port:

Dockerfile
FROM ghcr.io/ggml-org/llama.cpp:server-b12124
ADD https://huggingface.co/ggml-org/gemma-3-270m-it-GGUF/resolve/main/gemma-3-270m-it-Q8_0.gguf /models/model.gguf
CMD ["--model", "/models/model.gguf", "--host", "0.0.0.0", "--port", "8080"]

Container environment

Clever Cloud starts the container with:

  • The environment variables of your application, such as the credentials of the add-ons you link to it
  • A memory limit based on the memory available on the instance, without swap
  • A limit of 1024 open files, which processes can raise up to 524288

The container writes its logs to its standard output and error: Clever Cloud collects them as the logs of your application.

Build phase

On a new build, Clever Cloud builds the image with Buildx. The build context is the root of your project, or the folder set in CC_APP_FOLDER. Set CC_DOCKER_BUILDX=false to use the legacy builder instead (deprecated, and to be removed).

Clever Cloud passes each environment variable of your application with --build-arg. Declare the ones a build step needs with an ARG instruction. For instance, a Vite application embeds its VITE_* variables in its files at build time. With a VITE_API_URL environment variable, this Dockerfile builds the application, then serves it with Nginx. Declare ARG in the stage that uses it:

Dockerfile
FROM node:26-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ARG VITE_API_URL
RUN npm run build

FROM nginxinc/nginx-unprivileged:alpine
COPY --from=build /app/dist /usr/share/nginx/html

Each new commit builds the image from scratch: Clever Cloud doesn’t keep the Docker layers between builds, base image included. Restarting the application without a code change reuses the image of the build cache when it’s available, without building it again. Thus, a new value of a build variable, such as VITE_API_URL in the above example, only applies after a rebuild.

To build again from scratch, restart without the cache (rebuild):

clever restart --without-cache

If a build fails for lack of memory, enable a dedicated build instance larger than your application instances.

Optimize your image

Clever Cloud saves the image as the build cache of the commit, and loads it again on restart: a smaller image is faster to save and to restore. To keep yours small and safe:

  • Exclude what the build doesn’t need, such as .git or node_modules, with a .dockerignore file
  • Use a multi-stage build, as in the Vite example: build in a first stage, and copy only the result into the final image
  • Start from a small base image, such as an alpine or slim variant, with a pinned version tag, or from scratch
  • Run your application as a non-root user, with the USER instruction or from an unprivileged image such as nginxinc/nginx-unprivileged

Learn more in the Docker build best practices.

Deploy a static binary from scratch

scratch is an empty image. For a program compiled as a static binary, such as a Go or Rust program, copy only the binary into it: the image is then barely larger than the binary. For instance, for a Go web server:

Dockerfile
FROM golang:1.27-alpine AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o /server

FROM scratch
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=build /server /server
CMD ["/server"]

Such an image only holds what you copy into it, without the certificate authorities other images include. Most apps read them from the system to check HTTPS servers: without the COPY of the certificates, HTTPS requests fail with x509: certificate signed by unknown authority. It has no shell either: SSH access doesn’t work, and CC_RUN_SUCCEEDED_HOOK can only run the programs you copy into the image.

Deploy a pre-built image

Clever Cloud always builds the image of your Dockerfile, but this Dockerfile can start from an image you build elsewhere, in your CI for instance, or from a ready-to-use image. Set this image in the FROM instruction. If it defines a CMD or an ENTRYPOINT and listens on port 8080, you don’t need anything else. Otherwise, add the CMD that starts your application, or set its port in CC_DOCKER_EXPOSED_HTTP_PORT.

For instance, to deploy Stirling-PDF, a ready-to-use PDF toolbox, a single line is enough. Its image already listens on port 8080:

Dockerfile
FROM stirlingtools/stirling-pdf:3.3.0

To pull the image from a private registry, log in to it. To deploy a new version, change its tag in the Dockerfile and push the commit. A restart reuses the image of the build cache. If you publish a new image under the same tag, restart without the cache to pull it.

Log in to a registry

To pull images from a private registry, or to raise the pull limits of Docker Hub, set registry credentials. Clever Cloud uses them with docker login before the build:

  • CC_DOCKER_LOGIN_USERNAME: the username
  • CC_DOCKER_LOGIN_PASSWORD: the password or an access token
  • CC_DOCKER_LOGIN_SERVER: the registry, such as ghcr.io. Without it, Clever Cloud logs in to Docker Hub

If one of the credentials is missing or the login fails, Clever Cloud builds the image without authentication.

Ports, Mapping, and Network Groups

The container receives HTTP traffic on port 8080, and the traffic of TCP redirections on port 4040. Its network depends on the ports it listens on. With the default ports, the container shares the network of the instance (--net host). If it’s part of a Network Group, the other members can reach every port your application listens on, such as an internal API on port 9000. It works as with any other runtime.

If your container needs to map ports 8080 and 4040 of the instance to other ports, set them in CC_DOCKER_EXPOSED_HTTP_PORT and CC_DOCKER_EXPOSED_TCP_PORT. Docker then uses -p 8080:<http_port> and -p 4040:<tcp_port>, and the container doesn’t share the network of the instance anymore. In such a configuration, the other ports of the container are unreachable, even from a Network Group.

In both cases, your container reaches other Network Group members by their domain name: <member_id>.m.<ng_id>.cc-ng.cloud.

The PORT environment variable still holds 8080, even with an ENV PORT instruction in your Dockerfile. If your application reads it, set PORT in the environment variables of your application, to the value of CC_DOCKER_EXPOSED_HTTP_PORT.

To enable IPv6 in the Docker daemon, set an IPv6 range in CIDR notation in CC_DOCKER_FIXED_CIDR_V6, such as fd00::/80.

Docker socket access

Some containers need the Docker socket, to start sibling containers for instance. Set CC_MOUNT_DOCKER_SOCKET=true to mount it in /var/run/docker.sock. Docker then runs your container, and the ones it starts, with user namespace remapping: the root user of a container is an unprivileged user on the instance. Your container also receives its traffic through port mapping, not on the network of the instance.

The Docker socket gives control over the instance

A container with access to the Docker socket controls the Docker daemon of the instance. Don’t give it to code you don’t trust.

Docker applications as Clever Tasks

A Docker container can run as a Clever Task, such as a job or a migration. Clever Cloud builds the image, runs the container, and stops the task when the container exits. Configure an application as Tasks from the Information panel in the Console or with Clever Tools.

A Docker task runs the CMD or ENTRYPOINT of the image, not CC_RUN_COMMAND, nor the command you give to clever create --task. Build an image whose command exits once it finishes its work, or the task keeps running.

Examples

Last updated on