Hyphen Hyphen
Log In

Introduction

Deploy

ENV Secrets Management

Feature Flags

URL Shortening

Net.Info

Integrations

GitHub Actions

Policies

Hyphen Deploy Quickstart

A quickstart guide to deploying containerized applications using Hyphen Deploy. Learn how to connect cloud providers, set up projects, use the CLI, and configure deployments for AWS, Azure, and Google Cloud.

🚧 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:

Table of Contents

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

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

hx init

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.

Configure Your Project Environment Deployment Settings

Each deployment is scoped to a single project environment. So in order to deploy both development and production, each environment will need to be configured and deployed.

Back in the Hyphen app:

  1. Navigate to the project containing the app(s) you want to deploy. By default, the development environment is selected. Click the Create Deployment button to configure the environment's deployment settings.
  2. In Deployment Settings, choose the default deployment target or targets (e.g. Microsoft Azxure), availability tier, and traffic region or regions for this environment. These settings apply to all apps in the deployment unless you override them for a specific app.
  3. Under Apps in this deployment, turn on each app you want to include in the deployment. Learn more about environment variables or secrets if your build requires them.
  4. For each included app, configure the app-specific settings:
    • Select the scale size.
    • Optionally configure a hostname by entering a subdomain, selecting a domain, and adding a path. A hostname is required if you will be using deployment previews.
    • If needed, enable Customize cloud target, availability and traffic region for this app to override the deployment defaults for that app.
  5. Optionally add a description for the deployment.
  6. Select Save to save your deployment.

Repeat this process to create a separate deployment for each additional environment (e.g. production).

Deploy your app

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

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

hx deploy

The ID of the deployment is available in the url when looking at the deployment 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