Guides
Start typing to search…

Builds

How Hyphen Deploy builds your Docker images

When you deploy your application with Hyphen, the platform automatically builds your Docker image, pushes it to your project's container registry, and deploys it to your cloud infrastructure. This streamlined process ensures that your latest code changes are packaged consistently and securely deployed.

How Builds Work

Builds in Hyphen Deploy are triggered when you run a deployment or manually with the hx build command. The build process happens locally on your machine or in your CI/CD environment, then the resulting Docker image is pushed to your project's container registry in your cloud provider.

When you run hx deploy, Hyphen:

  1. Locates your Dockerfile in the repository
  2. If no Dockerfile exists, Hyphen Code generates one automatically based on your application's code
  3. Builds a Docker image using your Dockerfile
  4. Inspects the image to detect exposed ports
  5. Authenticates with your project's container registry
  6. Pushes the image to the registry with appropriate tags
  7. Registers the build with Hyphen and proceeds with deployment

The entire build process is tracked and logged, so you can monitor progress and troubleshoot any issues that arise.

Build Process Details

Finding Your Dockerfile

Hyphen automatically searches your repository for a Dockerfile. If no Dockerfile is found, Hyphen Code will automatically generate one for you based on your application's code and dependencies. The generation process:

  • Analyzes your codebase and detects the programming language, framework, and build system
  • Creates an optimized Dockerfile tailored to your application
  • Saves the generated Dockerfile and .dockerignore locally (allowing you to review before committing)

Building the Docker Image

The Docker build process uses your Dockerfile to create a container image. Hyphen builds images targeting the linux/amd64 platform by default, ensuring compatibility with the most common cloud container services including AWS ECS, Azure Container Apps, and Google Cloud Run.

The image is tagged with your app name and the current Git commit SHA (shortened to 7 characters), making it easy to track which code version is deployed.

Port Detection

After building the image, Hyphen inspects it to automatically detect which ports your application exposes. This information is used to configure networking and load balancing when your application is deployed.

Ports are detected from the EXPOSE directive in your Dockerfile.

Pushing to Container Registry

Once built, the image is pushed to your project's container registry. Hyphen handles authentication automatically, logging in with the credentials configured when you set up your container registry integration.

The image is tagged appropriately for your registry type:

  • AWS ECR: Uses : as the separator with tag format registry:image-tag
  • Azure ACR: Uses / as the separator with tag format registry/image:tag
  • Google Artifact Registry: Uses / as the separator with tag format registry/image:tag

After the push completes, Hyphen logs out of the registry to avoid leaving credentials in your local Docker configuration.

Registering the Build

Builds are associated with a specific environment (e.g., development, production) or available to all environments. When you run a deployment, Hyphen automatically uses the latest build for that environment.

Additional metadata is recorded with each build:

  • The container image URI
  • Exposed ports
  • Git commit SHA
  • Build timestamp
  • Associated app and environment

This build record can be viewed in the Hyphen Dashboard and is used to track your deployment history.

Build Triggers

Builds can be triggered in several ways:

Via CLI

When you run hx deploy from your terminal, Hyphen builds your Docker image locally before initiating the deployment. The CLI streams build progress to your terminal, making it easy to monitor and debug.

hx deploy <deployment-policy-id>

For more details on using the CLI for deployments, see Deployment Run Methods.

Via GitHub Actions

When you use GitHub Actions to automate your deployments, the build happens in the GitHub Actions runner environment. The Hyphen/setup-hx-action installs the Hyphen CLI, which then builds your Docker image as part of the workflow.

For a detailed guide on setting up automated deployments with GitHub Actions, see GitHub Actions Deployment.

Container Registries

Build artifacts (Docker images) are stored in your project's container registry. This registry is created in your connected cloud provider and is dedicated to your project.

Each project needs a container registry configured before you can deploy. If you haven't set up a container registry yet, see the Deploy Quickstart guide.

Requirements

Before running a build, ensure you have:

  • Docker installed and available in your PATH
  • A container registry configured for your project
  • Successfully run hx init to initialize your app

A Dockerfile is not required but will be used if present. If not, Hyphen Code will generate one automatically.

Skipping Builds

If you want to deploy a previously built image without rebuilding, you can use the --no-build flag:

hx deploy <deployment-policy-id> --no-build

This is useful when you want to:

  • Redeploy the same build to a different environment
  • Retry a failed deployment without rebuilding
  • Test deployment configuration changes without code changes

When using --no-build, Hyphen will use the most recent build for your app.

Standalone Builds

You can also build and upload a Docker image without immediately deploying it using the hx build command. This is useful for testing your build process or preparing artifacts ahead of deployment.

For more information about the build command, see CLI documentation.

Next Steps

Updated 1 day ago