Configurations

Configuration management enables you to manage configurations for your applications with environment-specific overrides and automatic merging.

What are Configurations?

Configurations define how your applications behave in different environments. Examples of configurations include:

• Database connection strings
• API endpoints
• Feature flags
• Logging levels
• Timeouts and limits

In Hydra Deploy, you work with a base configuration per application and can define project-specific overrides that are automatically merged.

Configuration Types

Hydra Deploy supports the following configuration formats:

Merge Support: Means that base config and project overrides are automatically merged.

Base Configurations (Application Level)

Base configurations are defined at application level and contain the default values.

Creating a Base Config

1. Go to an application
2. Navigate to the Configurations tab
3. Click on Add Config File
4. Give the file a name (e.g., appsettings.json)
5. Select the type (JSON, XML, DOTENV, or TXT)
6. Enter the base configuration
7. Click on Save

Example JSON Base Config:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  },
  "api": {
    "timeout": 30,
    "retries": 3
  },
  "features": {
    "newFeature": false
  }
}

Example DOTENV Base Config:

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=myapp
API_TIMEOUT=30
API_RETRIES=3
NEW_FEATURE=false

Project Configuration Overrides

Project-specific overrides override specific values for the base configuration.

Creating an Override

1. Go to a project
2. Navigate to the Configurations tab
3. Select an application
4. Per environment, you can define overrides
5. Enter only the fields you want to override
6. Save the configuration

During deployment, the base configuration and project overrides will be automatically merged.

Example Override for Development:

{
  "database": {
    "host": "dev-db.local"
  },
  "features": {
    "newFeature": true
  }
}

Example Override for Production:

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

How Config Merging Works

During deployment, the base configuration and project overrides are automatically merged. The merge strategy depends on the config type.

JSON — Deep Merge

JSON configs are merged recursively. Nested objects are walked and merged key-by-key. Scalar values in the override win; keys not present in the override are kept from the base.

Base:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  },
  "features": {
    "darkMode": false,
    "betaUi": false
  }
}

Override:

{
  "database": {
    "host": "prod-db.example.com"
  },
  "features": {
    "darkMode": true,
    "betaUi": true
  }
}

Result:

{
  "database": {
    "host": "prod-db.example.com",
    "port": 5432,
    "name": "myapp"
  },
  "features": {
    "darkMode": true,
    "betaUi": true
  }
}

Arrays in JSON are replaced entirely by the override value, not merged element-by-element.

DOTENV — Key Override

Dotenv files (.env, .properties) are parsed line-by-line. Keys present in both are taken from the override. Keys only in the base are kept. New keys in the override are appended.

Base:

DB_HOST=localhost
DB_PORT=5432
APP_ENV=development
LOG_LEVEL=info

Override:

DB_HOST=prod.db.internal
APP_ENV=production
NEW_KEY=hello

Result:

DB_HOST=prod.db.internal
DB_PORT=5432
APP_ENV=production
LOG_LEVEL=info
NEW_KEY=hello

XML — Identity-Based Merge

XML configs use a smart merge that understands .NET-style config files with <add key="..." />, <add name="..." />, and similar patterns.

Rules:

1. Keyed elements — elements with a key, name, or id attribute are matched by that identity. Matching elements are updated; new ones are appended.
2. Container nodes — plain wrapper elements (e.g. <appSettings>, <system.web>) are recursed into.
3. Incompatible elements — if base and override use different identity attributes on the same tag, the override wins outright (no merging).
4. Attributes — always overwritten by the override value.

Base:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="ApiUrl" value="http://localhost:5000"/>
    <add key="Timeout" value="30"/>
    <add key="Debug" value="true"/>
  </appSettings>
  <connectionStrings>
    <add name="Default" connectionString="Server=localhost;Database=mydb;"/>
  </connectionStrings>
</configuration>

Override:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="ApiUrl" value="https://api.prod.example.com"/>
    <add key="Debug" value="false"/>
    <add key="NewSetting" value="added"/>
  </appSettings>
  <connectionStrings>
    <add name="Default" connectionString="Server=prod.db;Database=mydb_prod;"/>
  </connectionStrings>
</configuration>

Result:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="ApiUrl" value="https://api.prod.example.com"/>
    <add key="Timeout" value="30"/>
    <add key="Debug" value="false"/>
    <add key="NewSetting" value="added"/>
  </appSettings>
  <connectionStrings>
    <add name="Default" connectionString="Server=prod.db;Database=mydb_prod;"/>
  </connectionStrings>
</configuration>

ApiUrl and Debug were updated in-place, Timeout was kept from the base, and NewSetting was appended.

TXT — Full Replace

Plain text configs are not merged. The override completely replaces the base content.

Configuration Editor

Hydra Deploy has a powerful configuration editor:

Features:

• Syntax Highlighting - Colors for different types
• Validation - Immediate feedback on errors
• Environment Tabs - Switch between different environments
• Merge Preview - See how configs are merged
• Formatting - Automatic formatting

Using Config Editor:

1. Open an application or project configuration
2. Select the environment (in project config editor)
3. Edit the configuration
4. Click on Save to save

Version-Specific Configurations

You can define configurations that are specific to certain versions of an application.

Use Case:

• Version 1.0 has a configuration structure
• Version 2.0 has a new configuration structure
• You can define a different config for each version

How it Works:

1. Go to application configurations
2. Select a version in the version dropdown
3. Define or modify the configuration for that specific version
4. On deployment, the correct version-specific config is used

Configuration Best Practices

DRY (Don’t Repeat Yourself)

• Define only standard values in base config
• Override only what needs to be different per project/environment
• Avoid duplication of configuration

Environment Variables for Sensitive Data

Use environment variables for sensitive information:

• Passwords
• API keys
• Connection strings

Example:

{
  "database": {
    "host": "${DB_HOST}",
    "port": "${DB_PORT}",
    "username": "${DB_USERNAME}",
    "password": "${DB_PASSWORD}"
  }
}

These variables can then be filled in on the server via deployment script or via the agent configuration.

Validation

• Validate configurations before you deploy
• Use JSON schema or XML schema if available
• Test configurations in a staging environment

Documentation

• Document what each configuration option does
• Add comments to your configuration files
• Keep a changelog for configuration changes

Complex Configurations

Nested Objects

JSON and XML support nested objects that are merged correctly:

Base:

{
  "server": {
    "port": 3000,
    "ssl": {
      "enabled": false
    }
  }
}

Override:

{
  "server": {
    "ssl": {
      "enabled": true,
      "certPath": "/etc/ssl/cert.pem"
    }
  }
}

Result:

{
  "server": {
    "port": 3000,
    "ssl": {
      "enabled": true,
      "certPath": "/etc/ssl/cert.pem"
    }
  }
}

Arrays

Arrays are completely overwritten, not merged:

Base:

{
  "allowedHosts": ["localhost", "127.0.0.1"]
}

Override:

{
  "allowedHosts": ["*.example.com"]
}

Result:

{
  "allowedHosts": ["*.example.com"]
}

Configuration Error Handling

If a configuration is invalid:

• Error message is shown in the editor
• Deployment is blocked until configuration is correct
• Use validation to detect errors early

Configuration Templates

For common configurations, you can use templates:

Database Config Template:

{
  "database": {
    "host": "${DB_HOST}",
    "port": "${DB_PORT}",
    "name": "${DB_NAME}",
    "ssl": false,
    "pool": {
      "min": 2,
      "max": 10
    }
  }
}

API Config Template:

{
  "api": {
    "baseUrl": "${API_BASE_URL}",
    "timeout": 30,
    "retries": 3,
    "headers": {
      "User-Agent": "MyApp/1.0"
    }
  }
}

Configuration Security

Sensitive Data

• Don’t store passwords or API keys in configuration files
• Use environment variables instead
• Restrict access to sensitive configurations

Configuration Encryption

Hydra Deploy supports encryption of sensitive configuration values. Contact your system administrator for more information.

Access Control

Only users with the correct roles can modify configurations:

• ORG_OWNER - Full access
• ORG_MANAGER - Can modify configurations
• ORG_USER - Read only