Merge pull request #119 from deploystackio/main

update IaC lifecycle documentation and add new diagram

Author: Lasim

.gitignore

@@ -51,13 +51,11 @@ ehthumbs.db
 *.iml
 *.ipr
 *.iws
+._*.png
+._*.webp
+._*.svg
+
 
 # Tests
 coverage/
 .jest/
-
-# Vitepress
-.vitepress/dist
-.vitepress/cache
-.backup
-.remark-cache/

docs/assets/images/deploystack/deploystack-iac-flow-via-github-app.drawio

@@ -0,0 +1,69 @@
+<mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/26.0.9 Chrome/128.0.6613.186 Electron/32.2.5 Safari/537.36" version="26.0.9">
+  <diagram name="Seite-1" id="Gjpo2csS5-b6mWFYLMsI">
+    <mxGraphModel dx="1114" dy="794" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1100" pageHeight="850" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-2" value="App Project Repository" style="swimlane;fontStyle=1;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;" vertex="1" parent="1">
+          <mxGeometry x="80" y="80" width="240" height="90" as="geometry">
+            <mxRectangle x="40" y="40" width="100" height="30" as="alternateBounds" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-3" value="I.e.: Change file:" style="text;strokeColor=none;fillColor=default;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;" vertex="1" parent="DkQQ7b9g_ovJa4es4mWr-2">
+          <mxGeometry y="30" width="240" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-4" value=".deploystack/docker-run.txt" style="text;strokeColor=none;fillColor=default;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;fontFamily=Courier New;" vertex="1" parent="DkQQ7b9g_ovJa4es4mWr-2">
+          <mxGeometry y="60" width="240" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="DkQQ7b9g_ovJa4es4mWr-7" target="DkQQ7b9g_ovJa4es4mWr-10">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-7" value="DeployStack GitHub App&lt;div&gt;Event on file Change&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="400" y="95" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-8" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="DkQQ7b9g_ovJa4es4mWr-3" target="DkQQ7b9g_ovJa4es4mWr-7">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-18" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="DkQQ7b9g_ovJa4es4mWr-9" target="DkQQ7b9g_ovJa4es4mWr-15">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-9" value="DeployStack Backend" style="swimlane;fontStyle=1;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;" vertex="1" parent="1">
+          <mxGeometry x="640" y="80" width="230" height="90" as="geometry">
+            <mxRectangle x="40" y="40" width="100" height="30" as="alternateBounds" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-10" value="Validate Change within .deploystack" style="text;strokeColor=none;fillColor=default;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;" vertex="1" parent="DkQQ7b9g_ovJa4es4mWr-9">
+          <mxGeometry y="30" width="230" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-12" value="directory" style="text;strokeColor=none;fillColor=default;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;" vertex="1" parent="DkQQ7b9g_ovJa4es4mWr-9">
+          <mxGeometry y="60" width="230" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-14" value="DeployStack Backend" style="swimlane;fontStyle=1;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;" vertex="1" parent="1">
+          <mxGeometry x="120" y="240" width="230" height="90" as="geometry">
+            <mxRectangle x="40" y="40" width="100" height="30" as="alternateBounds" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-15" value="Re-create IaC templates with new" style="text;strokeColor=none;fillColor=default;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;" vertex="1" parent="DkQQ7b9g_ovJa4es4mWr-14">
+          <mxGeometry y="30" width="230" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-17" value="values from docker-run.txt file" style="text;strokeColor=none;fillColor=default;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;" vertex="1" parent="DkQQ7b9g_ovJa4es4mWr-14">
+          <mxGeometry y="60" width="230" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-19" value="deploy-templates repository" style="swimlane;fontStyle=1;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;" vertex="1" parent="1">
+          <mxGeometry x="450" y="240" width="230" height="90" as="geometry">
+            <mxRectangle x="40" y="40" width="100" height="30" as="alternateBounds" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-20" value="Push changes to IaC public repository" style="text;strokeColor=none;fillColor=default;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;" vertex="1" parent="DkQQ7b9g_ovJa4es4mWr-19">
+          <mxGeometry y="30" width="230" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-21" value="deploystackio/deploy-templates" style="text;strokeColor=none;fillColor=default;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;" vertex="1" parent="DkQQ7b9g_ovJa4es4mWr-19">
+          <mxGeometry y="60" width="230" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="DkQQ7b9g_ovJa4es4mWr-22" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="DkQQ7b9g_ovJa4es4mWr-15" target="DkQQ7b9g_ovJa4es4mWr-20">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

docs/assets/images/deploystack/deploystack-iac-flow-via-github-app.webp

@@ -26,7 +26,31 @@ Install the [DeployStack Repository Sync](/docs/deploystack/github-application.m
 - Cloud providers update their IaC specifications
 - DeployStack improves its template generation
 
-![DeployStack IaC Lifecycle](/docs/assets/images/deploystack/iac-lifecycle.drawio.svg)
+![DeployStack IaC Lifecycle](/docs/assets/images/deploystack/iac-lifecycle.webp)
+
+## Update Flow
+
+As the app GitHub repository owner, an update flow gives you control over the generation of Infrastructure as Code (IaC) templates. The flow allows you to regenerate IaC templates by changing, for example, the `.deploystack/docker-compose.yml` file.
+
+All IaC templates are stored in public and open-source repository: [https://github.com/deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates).
+
+### Prerequisites for activating the flow
+
+1. You have installed the [DeployStack GitHub app](/docs/deploystack/github-application.md).
+2. You have created the `.deploystack/docker-run.txt` or `.deploystack/docker-compose.yml` file.
+
+The choice between `docker-run.txt` or `docker-compose.yml` depends on the submission process used to DeployStack. When submitting to DeployStack, you can choose two methods -> Docker Run or Docker Compose.
+
+### Example flow
+
+Let's say you want to change your image tag from "deploystack/awesomeapp:v1" to "deploystack/awesomeapp:v2-next".
+
+![DeployStack IaC Lifecycle](/docs/assets/images/deploystack/deploystack-iac-flow-via-github-app.webp)
+
+1. To do this, you will edit the file `.deploy stack/docker-run.txt` and change your new docker tag
+2. GitHub will send an event to the DeployStack backend with the change of the file `.deploy stack/docker-run.txt` because you have the DeployStack GitHub app installed.
+3. DeployStack backend validates the change, and if everything test passes
+4. By using [docker-to-iac module](https://github.com/deploystackio/docker-to-iac), DeployStack backend will generate the new IaC templates for your application and store them in our repository [https://github.com/deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates)
 
 ## Update Triggers
 

docs/assets/images/deploystack/iac-lifecycle.webp

@@ -29,29 +29,40 @@ console.log(parsers);
   {
     providerWebsite: 'https://aws.amazon.com/cloudformation/',
     providerName: 'Amazon Web Services',
-    provieerNameAbbreviation: 'AWS',
+    providerNameAbbreviation: 'AWS',
     languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html',
     languageAbbreviation: 'CFN',
     languageName: 'AWS CloudFormation',
-    defaultParserConfig: { fileName: 'aws-cloudformation.yaml', cpu: 512, memory: '1GB', templateFormat: 'yaml' }
+    defaultParserConfig: { files: [Array], cpu: 512, memory: '1GB' }
   },
   {
     providerWebsite: 'https://render.com/docs',
     providerName: 'Render',
-    provieerNameAbbreviation: 'RND',
+    providerNameAbbreviation: 'RND',
     languageOfficialDocs: 'https://docs.render.com/infrastructure-as-code',
     languageAbbreviation: 'RND',
     languageName: 'Render Blue Print',
     defaultParserConfig: {
-      subscriptionName: 'free',
+      files: [Array],
+      subscriptionName: 'starter',
       region: 'oregon',
-      fileName: 'render.yaml',
-      templateFormat: 'yaml'
+      diskSizeGB: 10
     }
+  },
+  {
+    providerWebsite: 'https://www.digitalocean.com/',
+    providerName: 'DigitalOcean',
+    providerNameAbbreviation: 'DO',
+    languageOfficialDocs: 'https://docs.digitalocean.com/products/app-platform/',
+    languageAbbreviation: 'DOP',
+    languageName: 'DigitalOcean App Spec',
+    defaultParserConfig: { files: [Array], region: 'nyc', subscriptionName: 'basic-xxs' }
   }
 ]
 ```
 
+**Note the files array**: that's because we have a [multi file strategy](/docs/docker-to-iac/multi-file-configuration.md).
+
 ### Type
 
 ```typescript
@@ -77,13 +88,24 @@ console.log(awsInfo);
 
 ```json
 {
-    providerWebsite: 'https://aws.amazon.com/cloudformation/',
-    providerName: 'Amazon Web Services',
-    provieerNameAbbreviation: 'AWS',
-    languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html',
-    languageAbbreviation: 'CFN',
-    languageName: 'AWS CloudFormation',
-    defaultParserConfig: { fileName: 'aws-cloudformation.yaml', cpu: 512, memory: '1GB', templateFormat: 'yaml' }
+  providerWebsite: 'https://aws.amazon.com/cloudformation/',
+  providerName: 'Amazon Web Services',
+  providerNameAbbreviation: 'AWS',
+  languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html',
+  languageAbbreviation: 'CFN',
+  languageName: 'AWS CloudFormation',
+  defaultParserConfig: {
+    files: [
+      {
+        path: 'aws-cloudformation.cf.yml',
+        templateFormat: 'yaml',
+        isMain: true,
+        description: 'AWS CloudFormation template'
+      }
+    ],
+    cpu: 512,
+    memory: '1GB'
+  }
 }
 ```
 
@@ -107,75 +129,117 @@ translate(input: string, options: {
   environmentVariableGeneration?: EnvironmentVariableGenerationConfig;
   environmentVariables?: Record<string, string>;
   persistenceKey?: string;
-}): any
+}): TranslationResult
+```
+
+Where `TranslationResult` has the structure:
+
+```typescript
+interface TranslationResult {
+  files: { 
+    [path: string]: FileOutput 
+  };
+}
+
+interface FileOutput {
+  content: string;
+  format: TemplateFormat;
+  isMain?: boolean;
+}
 ```
 
 ### Examples
 
 #### Translating Docker Compose
 
 ```javascript
-import { readFileSync, writeFileSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
 import { translate } from '@deploystack/docker-to-iac';
 
 const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8');
 
-const translatedConfig = translate(dockerComposeContent, {
+const result = translate(dockerComposeContent, {
   source: 'compose',
   target: 'CFN',
   templateFormat: 'yaml'
 });
-console.log(translatedConfig);
+
+// Access individual file contents
+console.log(`Generated ${Object.keys(result.files).length} files:`);
+Object.keys(result.files).forEach(path => {
+  console.log(`- ${path}`);
+});
+
+// Write files to disk preserving directory structure
+Object.entries(result.files).forEach(([path, fileData]) => {
+  const fullPath = join('output', path);
+  const dir = dirname(fullPath);
+  
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  
+  writeFileSync(fullPath, fileData.content);
+});
 ```
 
 #### Translating Docker Run Command
 
 ```javascript
 import { translate } from '@deploystack/docker-to-iac';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
 
 const dockerRunCommand = 'docker run -d -p 8080:80 nginx:latest';
 
-const translatedConfig = translate(dockerRunCommand, {
+const result = translate(dockerRunCommand, {
   source: 'run',
-  target: 'CFN',
+  target: 'RND',
   templateFormat: 'yaml'
 });
-console.log(translatedConfig);
+
+console.log(result)
+
+// Access and save all generated files
+Object.entries(result.files).forEach(([path, fileData]) => {
+  const fullPath = join('output', path);
+  const dir = dirname(fullPath);
+  
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  
+  writeFileSync(fullPath, fileData.content);
+  console.log(`Created: ${path}`);
+});
 ```
 
 ### Example Output (AWS CloudFormation)
 
 ```yaml
-AWSTemplateFormatVersion: 2010-09-09
-Description: Generated from container configuration by docker-to-iac
-Parameters:
-  VPC:
-    Type: AWS::EC2::VPC::Id
-  SubnetA:
-    Type: AWS::EC2::Subnet::Id
-  SubnetB:
-    Type: AWS::EC2::Subnet::Id
-  ServiceName:
-    Type: String
-    Default: DeployStackService
-Resources:
-  Cluster:
-    Type: AWS::ECS::Cluster
-    Properties:
-      ClusterName: !Join ['', [!Ref ServiceName, Cluster]]
-  ExecutionRole:
-    Type: AWS::IAM::Role
-    Properties:
-      RoleName: !Join ['', [!Ref ServiceName, ExecutionRole]]
-      AssumeRolePolicyDocument:
-        Statement:
-          - Effect: Allow
-            Principal:
-              Service: ecs-tasks.amazonaws.com
-            Action: sts:AssumeRole
-      ManagedPolicyArns:
-        - arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
-...
+{
+  files: {
+    'render.yaml': {
+      content: 'services:\n' +
+        '  - name: default\n' +
+        '    type: web\n' +
+        '    env: docker\n' +
+        '    runtime: image\n' +
+        '    image:\n' +
+        '      url: docker.io/library/nginx:latest\n' +
+        '    startCommand: ""\n' +
+        '    plan: starter\n' +
+        '    region: oregon\n' +
+        '    envVars:\n' +
+        '      - key: PORT\n' +
+        '        value: "80"\n',
+      format: 'yaml',
+      isMain: true
+    }
+  }
+}
+Created: render.yaml
 ```
 
 #### Translation with Environment Variable Generation