DeployStack Configuration File Reference

The .deploystack/config.yml file allows you to customize how your application appears in the DeployStack catalog and deployment interfaces. This configuration file supports automatic validation in popular IDEs through SchemaStore integration.

Configuration File Location

Create a config.yml file in your repository's .deploystack directory:

your-repository/
├── .deploystack/
│   ├── config.yml
│   └── docker-compose.yml (example, or docker-run.txt)
└── README.md

Basic Configuration

Here's a minimal configuration example:

application:
  name: "My Application"
  description: "A scalable web application with Redis caching"
  logo: "https://example.com/path/to/logo.png"

Configuration Options

Application Settings

When you submit a repository to DeployStack, we automatically use:

Repository name as the application name
Repository description as the application description

You can override these values using the config.yml (only on your main branch) file:

Property	Type	Description	Constraints
`name`	String	Override the repository name for DeployStack display	Maximum 40 characters
`description`	String	Override the repository description for DeployStack display	Maximum 500 characters
`logo`	String	URL to your application logo	Application Logo Configuration

The override process follows this order:

DeployStack first uses your repository name and description
If present, values in .deploystack/config.yml override the repository metadata

Branch Deployment Settings

Before configuring multiple branch deployments, ensure you have installed the DeployStack Repository Sync GitHub App, as it's required for branch monitoring and template updates.

You can configure multiple branch deployments using the deployment.branches section:

Property	Type	Description	Constraints
`label`	String	Display name for the branch	Maximum 20 characters
`description`	String	Explain the branch's purpose or version	Maximum 100 characters
`active`	Boolean	Whether this branch is available for deployment	Optional, defaults to true
`priority`	Number	Order in which branches appear (lower numbers first)	Minimum value: 1
`exclude_providers`	Array	Optional list of cloud providers to exclude from template generation for this branch	Values must be valid provider codes: "aws", "rnd", "dop"

The default branch always has priority: 0 and appears first in the deployment options, regardless of other branch priorities.

Example configuration for multiple branches:

application:
  name: "My Application"
  description: "A scalable web application"

deployment:
  branches:
    v2:
      label: "Beta (v2.x)"
      description: "Preview of upcoming v2.x release"
      priority: 1
      exclude_providers:
        - "aws"  # Exclude AWS CloudFormation for this branch
    v3:
      label: "Alpha (v3.x)"
      description: "Early preview of v3.x"
      priority: 2

Each branch configuration allows you to:

Provide a user-friendly label for the version
Include a description explaining the branch's purpose
Control deployment availability with the active flag
Set display order using priority

When multiple branches are configured:

DeployStack generates separate deployment templates for each branch
Users can choose which version to deploy
The GitHub App monitors all configured branches for updates
The default branch is always listed first with implicit priority: 0

This is especially useful for projects that maintain multiple active versions simultaneously, such as stable and beta releases.

The optional exclude_providers array allows you to specify which cloud providers should be excluded from template generation for particular branches. This is useful when certain features in a branch version may not be compatible with specific cloud providers. Valid provider codes are:

Please check our current supported provider list here.

For example, if your beta version uses features only supported in DigitalOcean, you might exclude the other providers:

v2-beta:
  label: "Beta"
  description: "Beta version with DigitalOcean-specific features"
  exclude_providers:
    - "aws"
    - "rnd"

If no providers are excluded, templates will be generated for all supported cloud providers.

Service Connections

You can configure service-to-service communication for multi-container applications using the serviceConnections property within each branch configuration. This feature is particularly useful for applications where services need to communicate with each other (e.g., web apps connecting to databases).

Property	Type	Description	Constraints
`mappings`	Array	Defines relationships between services for connection configuration	Required
`mappings[].fromService`	String	Service that needs to connect to another service	Required
`mappings[].toService`	String	Service being connected to	Required
`mappings[].environmentVariables`	Array of Strings	Environment variable names that reference the target service	Required

Example configuration for service connections:

deployment:
  branches:
    main:
      label: "Production"
      description: "Production release"
      serviceConnections:
        mappings:
          - fromService: "app"
            toService: "db"
            environmentVariables:
              - "DATABASE_HOST"
              - "DATABASE_URL"
          - fromService: "frontend"
            toService: "api"
            environmentVariables:
              - "API_URL"

This configuration tells DeployStack how to properly configure communication between:

The "app" service and the "db" service through the DATABASE_HOST and DATABASE_URL environment variables
The "frontend" service and the "api" service through the API_URL environment variable

When templates are generated, DeployStack will transform these environment variables according to each cloud provider's specific service discovery mechanism:

For Render.com: Uses Blueprint's fromService syntax
For DigitalOcean App Platform: Uses direct service name references

For example, if your docker-compose.yml contains:

services:
  app:
    image: node:alpine
    environment:
      DATABASE_HOST: db
  db:
    image: mariadb:latest

The generated Render.com template would transform DATABASE_HOST to use their service discovery syntax:

services:
  - name: app
    # ...other configuration...
    envVars:
      - key: DATABASE_HOST
        fromService:
          name: db
          type: pserv
          property: hostport

Schema Validation

The configuration file is automatically validated against our JSON Schema when using supported IDEs (VS Code, IntelliJ, etc.). The schema is available at:

https://cdnx.deploystack.io/schema/config.yml.json

Notes

Changes to the configuration file are only processed when made on your repository's default branch
The logo URL must be accessible and point to a valid image file
All configuration properties are optional, but providing them improves your application's visibility in the DeployStack catalog

Usage Examples

Override Repository Metadata

application:
  name: "Redis Cache Manager"      # Overrides repository name
  description: "A more detailed description that better explains your application"  # Overrides repository description
  logo: "https://example.com/logos/redis-manager.png"

Configure Multiple Branch Deployments with Service Connections

deployment:
  branches:
    stable:
      label: "Stable"
      description: "Production-ready version"
      priority: 1
      serviceConnections:
        mappings:
          - fromService: "web"
            toService: "api"
            environmentVariables:
              - "API_ENDPOINT"
          - fromService: "api"
            toService: "db"
            environmentVariables:
              - "DB_HOST"
              - "DB_CONNECTION"
    
    beta:
      label: "Beta"
      description: "Preview of upcoming features"
      priority: 2
      exclude_providers:
        - "aws"  # Beta version not supported on AWS
      serviceConnections:
        mappings:
          - fromService: "web"
            toService: "api"
            environmentVariables:
              - "API_ENDPOINT"

Minimal Configuration example for logo update

Please visit our Application Logo Configuration page.

Edit on GitHub