Build

A Build is a compiled version of the code for each Service of an App.

Convox uses docker to compile code into a Build.

Build Definition

You can define the location to build for each Service in convox.yml.

services:
  api:
    build: ./api
  web:
    build:
      path: ./web
      manifest: Dockerfile.production

Command Line Interface

Creating a Build

    $ convox build -a myapp
    Packaging source... OK
    Uploading source... OK
    Starting build... OK
    ...
    Build: BABCDEFGHI
    Release: RBCDEFGHIJ

Every time a Build is created a new Release is created that references the Build.

Listing Builds

    $ convox builds -a myapp
    ID          STATUS    RELEASE     STARTED       ELAPSED
    BABCDEFGHI  complete  RBCDEFGHIJ  1 minute ago  25s

Getting Information about a Build

    $ convox builds info BABCDEFGHI -a myapp
    ID           BABCDEFGHI
    Status       complete
    Release      RBCDEFGHIJ
    Description
    Started      1 minute ago
    Elapsed      25s

Getting logs for a Build

    $ convox builds logs BABCDEFGHI -a myapp
    Sending build context to Docker daemon  4.2MB
    Step 1/34 : FROM golang AS development
    ...

Exporting a Build

    $ convox builds export BABCDEFGHI -a myapp -f /tmp/build.tgz
    Exporting build... OK

Importing a Build

    convox builds import -a myapp2 -f /tmp/build.tgz

Importing a Build creates a new Release that references the Build.

Build Arguments

Build arguments require rack version 3.22.0 or later.

Convox supports both custom build arguments and Convox-managed build arguments that provide build context information. Build arguments must be declared in your Dockerfile using the ARG instruction to be available during the build process.

Convox-Managed Build Arguments

Starting from version 3.22.0, Convox provides the following managed build arguments:

Argument	Description
`BUILD_APP`	The application name
`BUILD_AUTH`	Docker registry authentication credentials (contains sensitive data)
`BUILD_DEVELOPMENT`	Development environment flag
`BUILD_GENERATION`	Build generation identifier
`BUILD_ID`	Unique build identifier
`BUILD_MANIFEST`	Build manifest information
`BUILD_RACK`	Rack name
`BUILD_GIT_SHA`	Git commit SHA for the build

Using Build Arguments via CLI

Pass Convox-managed build arguments:

    $ convox build --build-args "BUILD_APP" --build-args "BUILD_ID" --build-args "BUILD_GIT_SHA"

Combine Convox-managed arguments with custom build arguments:

    $ convox build --build-args "BUILD_APP" --build-args "FOO=BAR" --build-args "VERSION=1.2.3"

Dockerfile Configuration

Important: Build arguments must be explicitly declared in your Dockerfile using the ARG instruction to be available during the build:

# Declare Convox-managed args
ARG BUILD_APP
ARG BUILD_ID
ARG BUILD_GIT_SHA
ARG BUILD_RACK

# Declare custom args
ARG FOO
ARG VERSION

# Use the args in your build
RUN echo "Building app: ${BUILD_APP} with version: ${BUILD_GIT_SHA}"

# Pass args to runtime environment if needed
ENV APP_VERSION=${BUILD_GIT_SHA}
ENV APP_NAME=${BUILD_APP}

Security Warning for BUILD_AUTH

Critical Security Notice: The BUILD_AUTH argument contains sensitive Docker registry authentication credentials including usernames and passwords/tokens. This data should never be:

Logged or printed during builds
Embedded in final images
Exposed in build output

Example of BUILD_AUTH content structure (contains sensitive data):

BUILD_AUTH: {"registry.url":{"Username":"AWS","Password":"[base64-encoded-token]"}}

Only use BUILD_AUTH when necessary for authenticating to private registries, and ensure it is not persisted in your final image layers.

Using Build Arguments with CI/CD Workflows

When using Convox Deployment and Review Workflows:

Navigate to your workflow configuration modal
Check the "Make Convox Managed Build Args Available" checkbox to include all Convox-managed build arguments
Use the custom build args input field to add your own arguments (e.g., FOO=BAR,VERSION=1.2.3)

Build Layers Caching

Convox uses buildkit to build and push images. Buildkit allows us to specify a caching path in remote repositories to store/fetch layers that have already been created. Unfortunately, the only rack registries that support such feature so far are Azure and DigitalOcean(DO racks have a built-in registry).

Using Docker Credentials in Builds

Docker Hub Rate Limiting

Convox supports using Docker Hub credentials to avoid rate limits imposed on anonymous pulls (100 pulls per 6 hours per source IP). When docker_hub_username and docker_hub_password are set as rack parameters, Docker Hub credentials are attached to build pods, convox run pods, service deployments, resource deployments (Redis, Postgres, MySQL, MariaDB, Memcached, PostGIS), and timer CronJobs — so every Convox-managed pull from Docker Hub is authenticated.

For AWS racks, ecr_docker_hub_cache complements Docker Hub credentials by serving resource images through an ECR pull-through cache, eliminating per-node Docker Hub pulls during node churn.

How to Use Docker Credentials in Convox

To use Docker Hub credentials during the build process, follow these steps:

Generate a read-only access token in Docker Hub:
- Log in to your Docker Hub account.
- Go to Account Settings and navigate to the Security tab.
- Under Access Tokens, click New Access Token.
- Set the access permissions to Read-only and generate the token.
Set the credentials for your Convox rack:

Run the following command to set the Docker Hub credentials on your rack. Be sure to use the read-only access token to avoid storing your Docker password in plain text.
```
$ convox rack params set docker_hub_username=<your-docker-hub-username> docker_hub_password=<your-read-only-token> -r <rackName>
```
Verify that the credentials have been set:

After setting the credentials, you can confirm they have been successfully configured by running:
```
$ convox rack params -r <rackName>
```

This will list the current parameters for the rack, including the Docker credentials.

Version Requirements

Basic build functionality: All versions
Convox-managed build arguments: Version 3.22.0+