Merge pull request #126 from deploystackio/main

latest prod release

Author: Lasim

README.md

@@ -2,9 +2,6 @@
 
 This repository contains the official documentation for the DeployStack ecosystem. Visit [deploystack.io](https://deploystack.io) to learn more about our platform.
 
-![GitHub Release](https://img.shields.io/github/v/release/deploystackio/documentation)
-![GitHub deployments](https://img.shields.io/github/deployments/deploystackio/documentation/Production?label=Production)
-
 ## Project Structure
 
 Key directories in this repository:

docs/deploystack/deploystack-config-file.md

@@ -43,9 +43,11 @@ You can override these values using the `config.yml` (only on your main branch)
 
 | 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](/docs/deploystack/application-logo-configuration.md) |
+| `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 |
+| `mappings[].property` | String | Type of connection property to reference (e.g., 'connectionString', 'hostport') | Optional, defaults to 'hostport' |
 
 The override process follows this order:
 
@@ -64,6 +66,7 @@ You can configure multiple branch deployments using the `deployment.branches` se
 | `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.
 
@@ -80,6 +83,8 @@ deployment:
       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"
@@ -102,6 +107,93 @@ When multiple branches are configured:
 
 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](/docs/docker-to-iac/parser/index.md).
+
+For example, if your beta version uses features only supported in DigitalOcean, you might exclude the other providers:
+
+```yaml
+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:
+
+```yaml
+deployment:
+  branches:
+    main:
+      label: "Production"
+      description: "Production release"
+      serviceConnections:
+        mappings:
+          - fromService: "app"
+            toService: "db"
+            environmentVariables:
+              - "DATABASE_HOST"
+              - "DATABASE_URL"
+            property: "connectionString"
+          - fromService: "frontend"
+            toService: "api"
+            environmentVariables:
+              - "API_URL"
+            property: "hostport"
+```
+
+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:
+
+```yaml
+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:
+
+```yaml
+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:
@@ -127,6 +219,41 @@ application:
   logo: "https://example.com/logos/redis-manager.png"
 ```
 
+### Configure Multiple Branch Deployments with Service Connections
+
+```yaml
+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](/docs/deploystack/application-logo-configuration.md) page.

docs/docker-to-iac/api.md

@@ -129,6 +129,7 @@ translate(input: string, options: {
   environmentVariableGeneration?: EnvironmentVariableGenerationConfig;
   environmentVariables?: Record<string, string>;
   persistenceKey?: string;
+  serviceConnections?: ServiceConnectionsConfig;
 }): TranslationResult
 ```
 
@@ -139,6 +140,7 @@ interface TranslationResult {
   files: { 
     [path: string]: FileOutput 
   };
+  serviceConnections?: ResolvedServiceConnection[];
 }
 
 interface FileOutput {
@@ -215,6 +217,45 @@ Object.entries(result.files).forEach(([path, fileData]) => {
 });
 ```
 
+#### Configuring Service Connections
+
+```javascript
+import { translate } from '@deploystack/docker-to-iac';
+
+const dockerComposeContent = `
+version: "3"
+services:
+  db:
+    image: mariadb:latest
+    environment:
+      - MYSQL_ROOT_PASSWORD=rootpass
+  app:
+    image: node:alpine
+    environment:
+      - DATABASE_HOST=db  # This will be transformed
+`;
+
+const result = translate(dockerComposeContent, {
+  source: 'compose',
+  target: 'DOP',  // DigitalOcean App Platform
+  templateFormat: 'yaml',
+  serviceConnections: {
+    mappings: [
+      {
+        fromService: 'app',        // Service that needs to connect
+        toService: 'db',           // Service to connect to
+        environmentVariables: [    // Env vars that reference the service
+          'DATABASE_HOST'
+        ]
+      }
+    ]
+  }
+});
+
+// The result will include transformed service references:
+console.log(result.serviceConnections);
+```
+
 ### Example Output (AWS CloudFormation)
 
 ```yaml
@@ -373,11 +414,73 @@ const result = translate(dockerConfig, {
 
 #### `options.persistenceKey?: string`
 
-Optional. The `persistenceKey` parameter allows you to maintain consistent variable values across multiple template generations
+Optional. The `persistenceKey` parameter allows you to maintain consistent variable values across multiple template generations.
+
+#### `options.serviceConnections?: ServiceConnectionsConfig`
+
+Optional. Configure service-to-service communications by defining which environment variables reference other services.
+
+```typescript
+type ServiceConnectionsConfig = {
+  mappings: Array<{
+    fromService: string;         // Service that needs to connect
+    toService: string;           // Service to connect to
+    environmentVariables: string[]; // Environment variables that reference the service
+    property?: string;           // Connection property type (connectionString, hostport, etc.)
+  }>
+};
+```
+
+This option is currently supported by:
+
+- Render.com (RND): Uses Blueprint's `fromService` syntax
+- DigitalOcean App Platform (DOP): Uses direct service names
+
+Example:
+
+```javascript
+serviceConnections: {
+  mappings: [
+    {
+      fromService: 'frontend',
+      toService: 'api',
+      environmentVariables: ['API_URL'],
+      property: 'hostport'
+    },
+    {
+      fromService: 'app',
+      toService: 'db',
+      environmentVariables: ['DATABASE_URL'],
+      property: 'connectionString'
+    }
+  ]
+}
+```
 
 ### Return Value
 
-Returns the translated Infrastructure as Code template in the specified format. The structure and content will vary based on the target IaC language and template format chosen.
+Returns the translated Infrastructure as Code template and any resolved service connections:
+
+```typescript
+{
+  files: {
+    // Generated IaC template files with paths as keys
+    'render.yaml': { content: '...', format: 'yaml', isMain: true }
+  },
+  serviceConnections: [
+    {
+      fromService: 'app',
+      toService: 'db',
+      variables: {
+        'DATABASE_HOST': {
+          originalValue: 'db',
+          transformedValue: 'db'  // Transformed as appropriate for the provider
+        }
+      }
+    }
+  ]
+}
+```
 
 ## List Services API
 

docs/docker-to-iac/publishing-to-npm.md

@@ -5,7 +5,7 @@ menuTitle: Publishing to NPM
 
 # Publishing docker-to-iac module to NPM
 
-We have created an organization @deploystack for NPM. Publishing in NPM happens automatically through `semantic-release`. Config: [https://github.com/deploystackio/docker-to-iac/blob/main/.github/workflows/release.yml](https://github.com/deploystackio/docker-to-iac/blob/main/.github/workflows/release.yml)
+We have created an organization @deploystack for NPM. Publishing in NPM happens automatically through `semantic-release`. Config: [https://github.com/deploystackio/docker-to-iac/blob/main/.github/workflows/release-pr.yml](https://github.com/deploystackio/docker-to-iac/blob/main/.github/workflows/release-pr.yml)
 
 The prerequisite for a release is a successful pull request to the default branch `main`. This means that all tests must first be successfully completed. `semantic-release` creates a new version and automatically publishes the node package to: [https://www.npmjs.com/package/@deploystack/docker-to-iac](https://www.npmjs.com/package/@deploystack/docker-to-iac)