Hyphen
Log In

Builds

Learn how Hyphen CLI builds container images locally or in CI/CD, automatically pushes artifacts to multi-cloud container registries, and manages build records.

The Hyphen CLI builds a container image from the files in your local app folder and uploads it to your project's container registries. When a deployment targets more than one cloud (AWS, Azure, and/or Google Cloud), a single build produces one Docker artifact per cloud and pushes each image to that cloud's registry. You can then deploy that build to your cloud infrastructure. GitHub setup is optional for local builds.

Table of Contents

How Builds Work

Run hx build to build and upload images, or hx deploy to build, upload, and start a deployment. A dashboard deployment uses uploaded builds; it does not build files from your computer. The build process happens locally on your machine or in your CI/CD environment, then the resulting Docker image is pushed to each of the project's container registries.

When you run hx build or the build step of hx deploy, Hyphen:

  1. Locates your Dockerfile in the app folder
  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. Lists the project's container registries
  6. Authenticates with each registry and pushes the image
  7. Registers the build with Hyphen (one Docker artifact per pushed image)

The CLI reports build stages. Use --verbose when you need Docker build output for troubleshooting.

Build Process Details

Finding Your Dockerfile

Hyphen automatically searches your app folder 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 alternate ID and the current Git commit SHA, shortened to 7 characters. Without Git history, the CLI uses 0000000. This metadata does not change the source of the build: it uses the current local files, including uncommitted changes allowed by your Docker build context.

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 Registries

Once built, the image is pushed to every ready container registry configured on the project. Hyphen handles authentication automatically, logging in with the credentials configured when you set up each container registry connection.

The image is tagged appropriately for each 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 each push completes, Hyphen logs out of that registry to avoid leaving credentials in your local Docker configuration.

Registering the Build

Builds can be associated with an environment or preview. A normal CLI deployment uses the build just created for the local app and uploaded builds for other included apps. Dashboard deployments and --no-build reuse uploaded builds for the selected deployment target.

Additional metadata is recorded with each build:

  • Artifacts for each project registry the image was pushed to (image URI and cloud target)
  • Exposed ports
  • Git commit SHA, or a fallback value when no commit exists
  • Build timestamp
  • Associated app and environment

This build record can be viewed in the Hyphen Dashboard and is used to track your deployment history. During a deployment run, each cloud instance uses only the artifact whose target matches that cloud.

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. Add --verbose to see Docker build output.

hx deploy

Plain hx deploy selects the environment of type development in the project linked in your app folder's .hx file. Use hx deploy --env production for an explicitly selected environment in that project.

Use Copy CLI command in the menu beside Deploy to copy the selected environment and organization. Run it from the app folder whose .hx file links to the project shown in the menu.

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 registries. Each registry is created in a connected cloud provider and is dedicated to your project.

A build requires at least one ready container registry on the project. To deploy, the project also needs a ready registry and cloud workspace on every cloud the deployment targets. If you haven't set up registries yet, see the Deploy Quickstart guide.

When the project has registries on more than one cloud, a single build produces one artifact per registry and uploads each image accordingly. The build's details in the dashboard list every artifact.

Requirements

Before running a build, ensure you have:

  • Docker installed, available in your PATH, and running
  • At least one ready container registry on the project
  • Successfully run hx init to initialize your app

GitHub integration and a Git commit are not required for a local build. To deploy the build, the project also needs a ready cloud workspace connection for each cloud the deployment targets.

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 --env production --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 reuses uploaded builds for the selected deployment target. It does not upload local changes. For a preview, retain both --preview and --prefix in the command.

Standalone Builds

You can also build and upload Docker images without immediately deploying 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