When you deploy or build your application a “build” artifact is created. This consists of the Docker images that make up your application plus metadata stored in your Rack’s database. Each build has a unique ID and is associated with one or more releases.
Creating a Build
You can simply build your application by running
convox build from the top-level directory:
$ convox build
When you run this command the following steps are executed:
- The Convox CLI builds a tarball from all the files in your project (except the ones specified in
- The CLI uploads the tarball to your Rack
- The Rack extracts the tarball and reads
- Docker images are built or pulled as specified by
- The images are tagged and pushed into your Rack’s private Amazon ECR registry
- Build metadata is saved to the Rack
- A new release is created from the build and its metadata is saved too
The newly created release will not be promoted (made active) until you run
convox releases promote <release ID>.
If you’d like to build your app and promote the release in a single step, you can run
convox deploy rather than
Building From a Git Repository
You can tell Convox to build from a remote git repository rather than shipping your local files. To do so, pass the URL (with the .git extension) as an argument to
convox build. For example:
$ convox build https://github.com/myuser/myproject.git
This is the manual way to build from a git repository. For info on automated builds based on git actions please refer to Deploying to Convox.
convox builds to see a list of builds for your application.
convox builds info <build ID> to view metadata for a particular build.
convox builds logs <build ID> to view the logs for a particular build.
You can configure Convox Console to automatically build or deploy your app when it detects changes to your code repo. See Deploying to Convox for more info.
It’s possible to export a build from one app and import it to another app, even if the apps are on different Racks.
To move a build, first export it:
$ convox builds export <build ID> -a <appname> > build.tgz
You can then import the build into another app, even on a different Rack:
convox builds import -a <appname> < build.tgz
You can even pipe these commands together directly:
$ convox builds export <build ID> -a <app1> --rack <rack1> | convox builds import -a <app2> --rack <rack2>
Convox respects the
ARG Dockerfile directive. For more information, see Dockerfile: ARG.
Every invocation of
convox build uploads a tarball containing all of a project’s files to your Rack, no matter how many of the files in the build context actually changed. To optimize how these files are uploaded, run
convox build --incremental to upload the files to S3, where they remain cached. Subsequent incremental builds will upload only those files which differ from those in the preceding incremental build. This will significantly reduce the amount of data uploaded, meaning your Rack can begin building an image much sooner.