Guides
Start typing to search…

Hyphen Deploy Quickstart

Get started with Hyphen Deploy

🚧

At this time Hyphen Deploy supports containerized applications running on:

  • Amazon Elastic Container Service (ECS)
  • Azure Container Apps
  • Google Cloudrun

Hyphen Deploy takes your source code and turns it into a running application in your own cloud with minimal setup. You define requirements such as SLA, traffic location, and response time, and Hyphen generates a deployment configuration that is secure, consistent, and aligned with best practices.

The following cloud providers are currently supported:

Setup

1. Connect your cloud provider

Sign into the Hyphen app with a member account that has the organization admin role. In the main navigation, select Integrations, then select your cloud provider of choice.

Follow the instructions for connecting your cloud provider to your Hyphen org, which is typically just signing into the cloud provider with your user account, selecting an organization or tenant to connect to, and granting Hyphen the necessary permissions.

Once connected, you can choose to connect to another cloud provider for multi-cloud load balanced deployments, or move on to the next step.

2. Create a container registry for your project

A Project in Hyphen is a container that groups related apps, environments, and secrets, allowing teams to manage them together under a unified workflow. Projects provide a way to organize and control access to multiple apps and their environments, ensuring that secrets and configurations are securely stored and accessible to the appropriate team members.

Each project is linked to an Organization and can be accessed by users who have the appropriate permissions within that organization.

For a new project

In the Hyphen app, to create a new project:

  1. Click the "+" button in the header of the UI, and select Project.
  2. Enter a name (e.g. my-first-project)
  3. Under Project Integrations , check the container registry box to create a container registry in your organization's cloud. This is where build artifacts (e.g., Docker images) will be stored after being generated by the Hyphen Deploy build step.
  4. Your new project will be created with the default environments of development and production.

For an existing project

If you have an existing project without a container registry:

  1. Navigate to the Project overview.
  2. Under Integration Connections, click the + button next to Container Registry.
  3. Check the Container Registry box to create one in the cloud of your choice.
  4. Select Connect Project Container Registry to finalize.

3. Use the CLI to initialize your app

The Hyphen CLI (hx) is a command-line tool for running Hyphen commands locally from your terminal.

Install the CLI

For linux/macos

sh -c "$(curl -fsSL https://cdn.hyphen.ai/install/install.sh)"

For windows

powershell -c "irm https://cdn.hyphen.ai/install/install.ps1 | iex"

Authenticate with Hyphen

Authenticate by running:

hx auth

This starts the OAuth flow (opens a browser window, prompts you to sign in, and saves the credentials to your session).

Set the project and initialize your app

Set your project context:

hx set-project <project-id>

In the terminal, cd into the root directory of the app you want to deploy, then run

hx init <app-name>

This initializes your app with Hyphen and creates the .hx file and .env files for each environment.

Docker Containerization

If you're deploying a containerized application, hx init also creates a hyphen-entrypoint.sh script that automates environment variable management for your Docker containers.

This script handles:

  • Downloading the Hyphen CLI if not already present
  • Authenticating with your Hyphen API key
  • Pulling environment variables for the specified environment
  • Running your application with those variables loaded

To use it in your Dockerfile:

# Copy Hyphen configuration
COPY hyphen-entrypoint.sh ./hyphen-entrypoint.sh
RUN chmod +x ./hyphen-entrypoint.sh

# Use as entrypoint
ENTRYPOINT ["./hyphen-entrypoint.sh"]
CMD ["npm", "run", "start"]

When running your container, provide these environment variables:

  • HYPHEN_API_KEY: Your Hyphen API key
  • HYPHEN_APP_ENVIRONMENT: The environment name (e.g., "production")
  • HYPHEN_APP_ID: Your application ID (from .hx file)
  • HYPHEN_PROJECT_ID: Your project ID (from .hx file)
  • HYPHEN_ORGANIZATION_ID: Your organization ID (from .hx file)

4. (Optional) Connect DNS Zone

If you are deploying a service that will be accessible on the internet, add your DNS zone to manage the required DNS resource records automatically.

  1. Navigate DNS under the Settings section in the left navigation.
  2. Click Add Zone in the top left.
  3. Select your DNS Provider from the list of connected Integrations.
  4. Follow the next steps to select your zone from the provider.

Create a Deployment Policy

Back in the Hyphen app:

  1. Select the "+" button in the header of the UI, then select Deployment Policy.
  2. Name the deployment (e.g. deploy-to-dev)
  3. In the projects dropdown menu, select the project that contains the app you want to deploy.
  4. You will see a column for each environment in the project, such as development and production.
  5. Under development, select the app you want to deploy. You can also deploy multiple apps as part of the same policy, or deploy the same app to multiple environments. Learn more about environment variables or secrets if your build requires them.
  6. For each app-environment combination, configure deployment settings such as target cloud, availability, and scale size.
  7. Select Create Deployment to save your deployment policy.

Deploy your app

Now that you've created a deployment policy, it's time to build and package your app for deployment.

Back in the terminal run to build and deploy your app.

hx deploy <deployment-policy-id>

The ID of the deployment policy is available in the url when looking at the deployment policy detail.

While the run is in progress the CLI shows each build, release, and verification step in the order they are executed. When the deployment finishes you will receive a link to the generated preview environment as well as the run ID, which you can use to inspect logs in the Dashboard or reference the run from follow-up automation.

When deployment finishes, you'll get a link to access your running app.

Next Steps

Updated 1 day ago