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 if you receive an invitation link. All resources you create (applications, projects, etc.) will belong to your organization, and everyone within that organization will have access to them.

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 version numbers.

Versions

Application versions should ideally be created automatically through our public API within your CI/CD pipeline. This approach minimizes errors and ensures consistency. While manual version creation is possible through the interface, it’s less recommended.

Configuration

Most applications require configuration to function correctly in different environments. Within each application, you define the necessary configuration structures. Currently, we support JSON, XML, DOTENV, and TXT configuration formats. While TXT can be used for any config, it won’t be merged like the other formats.

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 Scripts

Each application needs a deployment script that defines how it should be deployed. This script is executed by the Hydra Deploy agent on the target server. If your server is Linux-based, you can use Bash scripts; if it’s Windows-based, you can use PowerShell scripts.

Agent

The Hydra Deploy Agent is a small application that runs on your server and executes deployment scripts. The agent communicates with Hydra Deploy’s servers using a socket connection.

Installation

To install the agent, download the agent.zip file from GitHub, 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 the “Settings” section of Hydra Deploy (only organization owners can do this). When creating an agent, you’ll receive an 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 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 will then handle deployments for the selected environments. If a deployment is triggered while the agent is offline, it will be queued and executed when the agent comes back online. Currently, agent assignment is done per environment. Future updates will allow for more granular control over which applications are deployed by which agent.

Projects

A Project is a collection of applications. It’s where you define environment-specific configuration overrides for the applications used in that project. These overrides are merged with the application’s base configuration during deployment. For example, you can have separate configuration overrides for your development and production environments. You should only define the differences from the default application configuration within the project, as the configurations are merged.

The application overview page shows which projects an application is used in and which versions are deployed where.

API Keys

API Keys are used to access Hydra Deploy’s public API. These keys grant access to your organization’s resources. Only organization owners can create new API keys. API keys are essential for automating application version creation and other tasks within your CI/CD pipeline.