Core Concepts

This section explains the fundamental concepts behind Hydra Deploy, providing a clear understanding of how its various components work together.

Organization

Everything within Hydra Deploy resides within an Organization. When you create a new account, you automatically create a new organization. Alternatively, you can join an existing organization by using an invite code during signup. All resources you create (applications, projects, agents, etc.) belong to your organization, and everyone within that organization can access them based on their role.

Organizations also store billing details (address, tax ID), a Stripe customer ID for payment processing, and a configurable release version pattern used across all projects.

Applications

Applications represent the individual components of your software, whether they are your own code or external tools like databases or message brokers. Think of them as the building blocks of your projects.

Each application has:

Name and Code: a human-readable name and a unique identifier
Image: an optional icon or logo for visual identification
Registry: an optional link to a package registry (Docker, npm, NuGet)
Private flag: when enabled, the application belongs to a single project and won’t appear in the “connect application” list for other projects
Deployment Steps: the steps that define how the application is deployed (see Deployment Steps)

Versions

Application versions track releases of your applications. Each version captures a snapshot of the application’s configuration files at the time of creation, ensuring deployments always use the configuration that was valid when the version was created.

Versions should ideally be created automatically through the External API within your CI/CD pipeline. This approach minimizes errors and ensures consistency. Manual version creation is also possible through the interface.

Mark as Broken: If a version causes issues, you can flag it as “broken.” Broken versions display a warning badge in the version list and trigger a prominent warning during the deploy review process. You can still deploy a broken version, but the warning helps your team proceed with caution. Broken status can be toggled on and off at any time.

Configuration

Most applications require configuration to function correctly in different environments. Within each application, you define the necessary configuration structures. Hydra Deploy supports six configuration formats:

JSON: deep-merged during deployment
YAML: deep-merged during deployment
TOML: deep-merged during deployment
XML: deep-merged during deployment
DOTENV: key-value merged during deployment
Text: plain text, replaced entirely (not merged)

Each configuration file has a deploy strategy that controls how it’s handled during deployment:

Merge (default): the base configuration is deep-merged with project-specific overrides
Override: the project override completely replaces the base configuration
Skip: the configuration file is not deployed at all

Hydra Deploy allows you to define partial configuration overrides within your projects (explained in the “Projects” section). For example, if your application has a JSON configuration like this:

{
  "database": {
    "host": "localhost",
    "port": 5432
  }
}

And within a project, you define a configuration override:

{
  "database": {
    "host": "production-db.example.com"
  }
}

Then, during deployment for that specific project, Hydra Deploy will merge these configurations, resulting in:

{
  "database": {
    "host": "production-db.example.com",
    "port": 5432
  }
}

This feature simplifies configuration management, reduces redundancy, and makes updates easier.

Deployment Steps

Each application needs deployment steps that define how it should be deployed. Hydra Deploy supports multiple step types:

Script: Bash scripts (Linux/Mac) or PowerShell scripts (Windows) executed by the agent
IIS: automated IIS website/app pool deployment on Windows servers
Kubernetes (K8s): Kubernetes deployment, service, and statefulset management
Email: send notification emails as part of the deployment process
Derived: steps inherited from a base template with project-specific overrides

Steps are ordered and executed sequentially during deployment. Each step has configurable variables that can vary per project and environment.

See Deployment Steps for full details.

Agent

The Hydra Deploy Agent is a lightweight application that runs on your server and executes deployment steps. The agent communicates with Hydra Deploy’s servers using a persistent WebSocket connection, providing real-time deployment progress and log streaming.

Agent Details

Each agent tracks:

Name: a descriptive name you choose (e.g., “Production Server”)
Key: a unique authentication key generated when you create the agent
Online status: whether the agent is currently connected
Version: the agent software version
OS: the operating system the agent is running on (auto-detected)

Installation

To install the agent, download the release from our GitHub repository, extract it to a folder on your server, and create a service that runs the agent executable.

Agent Configuration

You can create new agents under Settings > Agents (only organization owners and managers can do this). When creating an agent, you’ll receive a unique agent key. Start the agent executable with this key:

./agent --agent-key <agent-key>

After starting, the agent’s status should appear as “online” in the Hydra Deploy interface.

Agent Updates

Agents can be updated remotely through the Hydra Deploy interface. When a new agent version is available, you can initiate an update that the agent will download and apply automatically. Update progress is tracked with status and progress percentage.

Agent and Projects

To enable the agent to perform deployments, you need to connect it to the relevant projects. This is done on the Agents tab of a project page. The agent is assigned to specific environments. For example, Agent A handles “Production” while Agent B handles “Development.”

If a deployment is triggered while the agent is offline, it will be queued and executed when the agent comes back online.

Projects

A Project is a collection of applications that form a complete system. It’s where you define environment-specific configuration overrides for the applications used in that project.

Key features of projects:

Application connections: connect multiple applications to a project, with customizable display order
Environment connections: select which environments are relevant for this project
Configuration overrides: define per-environment config overrides that are merged with application base configs during deployment
Tags: assign colored tags to categorize and filter projects (see below)
Favorites: star projects for quick access; favorited projects appear at the top of your list
Activity sparkline: each project card shows a sparkline chart of recent deployment activity
Last deployed: timestamp of the most recent deployment for quick status checks

Project Tags

Tags help you organize projects visually. Each tag has a name and a color tone (main, main2, main3, teal, or amber). Tags are shared across the organization. Create them once, then assign them to any number of projects.

You can filter the projects list by one or more tags (OR semantics: a project matches if it carries any of the selected tags).

Sorting

The projects list supports multiple sort orders, saved to your browser’s local storage:

Last deployed (newest/oldest first)
Name (A-Z / Z-A)

Favorited projects always float to the top, regardless of the active sort.

Deployment Matrix

The project overview tab shows a deployment matrix: a visual grid showing every application, its versions, and the deployment status across all environments. You can deploy directly from the matrix by clicking on a version and environment combination.

Environments

Environments define the target stages for your deployments (e.g., Development, Staging, Production). Environments are organization-wide and can be connected to individual projects as needed.

The sort order of environments determines their display position in the deployment matrix and deploy review screens. Reorder them by dragging in Settings > Environments.

Registries

Registries represent package sources where your application artifacts are stored, such as Docker Hub, npm, NuGet, or other registries. You can link a registry to an application to track where its packages come from.

API Keys

API Keys provide programmatic access to Hydra Deploy’s External API. These keys grant access to your organization’s resources and are essential for automating application version creation, project setup, and other tasks within your CI/CD pipeline.

Each API key tracks its usage count and last-used timestamp for security monitoring.

Only users with the ORG_OWNER or ORG_MANAGER role can create API keys.

Authentication

Hydra Deploy supports two authentication methods:

Email/Password: traditional login with bcrypt-hashed passwords
Google OAuth: sign in with your Google account

Both methods issue JWT tokens stored as HTTP-only cookies. The JWT payload carries your user ID, username, roles, names, and organization.

Password Reset

If you forget your password, use the Forgot Password flow to receive a reset email with a time-limited token.

Dark Mode

Hydra Deploy supports both light and dark themes. Toggle between them using the sun/moon icon in the sidebar. Your preference is persisted across sessions.