Dockerfile

The Dockerfile describes the steps used to create a Build from your application code.

    FROM ubuntu:24.04
    COPY . .
    RUN ["deps", "install"]
    CMD ["bin/start"]

Common Directives

Directive	Description
FROM	defines the base image
COPY	add files from the local directory tree
RUN	execute a command
CMD	defines the default command to run on this image
ARG	define build variables

Optimizing Build Times

Each line of a Dockerfile will be cached as long as files referenced by it are not changed. This allows you to cache expensive steps such as dependency installation by selectively copying files before running commands.

The following example selectively copies only the files needed to run npm before installing dependencies.

    FROM node

    COPY package.json package-lock.json .
    RUN ["npm", "install"]

    COPY . .
    CMD ["npm", "start"]

The npm install will be cached on successive builds unless package.json or package-lock.json is changed.

.dockerignore

A .dockerignore file at the root of your source directory keeps files out of the build context. Convox applies the same pattern rules as docker build, including negation with ! to re-include a path underneath an excluded directory:

    node_modules
    tmp/**
    !tmp/keep-this
    *.log

Two details of that matching changed in rack version 3.25.3, in the convox CLI rather than on the Rack, so they apply once you update the CLI:

• A wildcard directory exclude combined with a re-include underneath it now excludes everything else under that directory. Earlier CLI versions leaked the other files under it into the build context.
• Patterns containing the regex characters +, (, ), and | are now treated literally, matching docker build.

Build Variables

Convox respects the ARG directive, allowing you to specify variables at build time.

This is useful for creating dynamic build environments, allowing you to use the same Dockerfile for varying deployments.

It is not recommended to use build variables for passing secrets. Values for build variables are embedded in the resulting image.

You can declare build variables using the ARG directive with an optional default value:

    ARG COPYRIGHT=2026
    ARG RUBY_VERSION

Values for these variables will be read from the Environment at build time:

    $ convox env set RUBY_VERSION=2.6.4

You can also pass build arguments directly via the CLI using the --build-args flag (requires rack version 3.22.0+). See Build Arguments for the full range of options including Convox-managed build arguments.

See Also

• Build Arguments for CLI-based build arguments and Convox-managed args
• Dockerfile: Best Practices
• Private Registries