diff --git a/docs/deploystack/docker-compose-requirements.md b/docs/deploystack/docker-compose-requirements.md index aebcdb4..a0aaffc 100644 --- a/docs/deploystack/docker-compose-requirements.md +++ b/docs/deploystack/docker-compose-requirements.md @@ -55,12 +55,24 @@ The infrastructure templates we generate require specific, immutable container i We currently support these Docker Compose properties -> please check [Supported Docker Compose Variables](/docs/docker-to-iac/supported-docker-compose-variables.md). +### Kubernetes/Helm + +When generating Helm charts for Kubernetes: + +- Database services (MySQL, PostgreSQL, Redis, etc.) are converted to Bitnami Helm chart dependencies +- Environment variables are split between ConfigMaps (regular variables) and Secrets (sensitive data) +- Each service in your Docker Compose becomes a separate Deployment and Service +- Volume mounts are supported and configured as needed + +This allows for better security practices and easier management of your application on Kubernetes. + ## Multiple Services Support DeployStack can handle Docker Compose files with multiple services, but support varies by cloud provider: - Some providers support deploying all services at once - Others will only deploy the first service in your compose file +- Kubernetes (Helm) supports multi-service deployments with each service becoming a separate Deployment Check the specific [Multi Services Support](/docs/docker-to-iac/multi-services-support.md) for details about multi-service support. diff --git a/docs/deploystack/one-click-deploy.md b/docs/deploystack/one-click-deploy.md index 84ee2cd..d896270 100644 --- a/docs/deploystack/one-click-deploy.md +++ b/docs/deploystack/one-click-deploy.md @@ -40,6 +40,7 @@ We create a dedicated branch for each project to support one-click deployment fu We integrate with cloud providers' native deployment systems. For example: - **DigitalOcean**: Uses the "Deploy to DigitalOcean" functionality as documented in their [official guide](https://docs.digitalocean.com/products/app-platform/how-to/add-deploy-do-button/) +- **Kubernetes**: Generates Helm charts that can be deployed to any Kubernetes cluster - Check [supported cloud providers](/docs/docker-to-iac/index.md) for full list ### Provider-Specific Templates @@ -50,6 +51,7 @@ Each cloud provider may require specific template formats: - DigitalOcean App Spec - Render Blueprints - And more based on provider requirements +- Kubernetes Helm charts with all necessary templates ## Using Deploy Buttons diff --git a/docs/docker-to-iac/api.md b/docs/docker-to-iac/api.md index be8282e..20c8272 100644 --- a/docs/docker-to-iac/api.md +++ b/docs/docker-to-iac/api.md @@ -49,6 +49,28 @@ console.log(parsers); 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' } + }, + { + providerWebsite: 'https://helm.sh/', + providerName: 'Kubernetes', + providerNameAbbreviation: 'K8S', + languageOfficialDocs: 'https://helm.sh/docs/', + languageAbbreviation: 'HELM', + languageName: 'Helm Chart', + defaultParserConfig: { + files: [Array], + cpu: '100m', + memory: '128Mi' + } + }, { providerWebsite: 'https://www.digitalocean.com/', providerName: 'DigitalOcean', @@ -217,6 +239,67 @@ Object.entries(result.files).forEach(([path, fileData]) => { }); ``` +#### Translating Docker Compose to Helm Chart + +```javascript +import { translate } from '@deploystack/docker-to-iac'; +import { writeFileSync, mkdirSync, existsSync } from 'fs'; +import { join, dirname } from 'path'; + +const dockerComposeContent = ` +version: '3' +services: + web: + image: nginx:latest + ports: + - "80:80" + db: + image: postgres:13 + environment: + POSTGRES_USER: myuser + POSTGRES_PASSWORD: mypassword + POSTGRES_DB: myapp +`; + +const result = translate(dockerComposeContent, { + source: 'compose', + target: 'HELM', + templateFormat: 'yaml' +}); + +// Access and save all generated files to create a complete Helm Chart +Object.entries(result.files).forEach(([path, fileData]) => { + const fullPath = join('helm-chart', path); + const dir = dirname(fullPath); + + if (!existsSync(dir)) { + mkdirSync(dir, { recursive: true }); + } + + writeFileSync(fullPath, fileData.content); + console.log(`Created: ${path}`); +}); +``` + +#### Example Output (Partial - Chart.yaml) + +```yaml +apiVersion: v2 +name: deploystack-app +description: A Helm chart for DeployStack application generated from Docker configuration +type: application +version: 0.1.0 +appVersion: 1.0.0 +maintainers: + - name: DeployStack + email: hello@deploystack.io +dependencies: + - name: db + repository: https://charts.bitnami.com/bitnami + version: ^12.0.0 + condition: dependencies.db.enabled +``` + #### Configuring Service Connections ```javascript @@ -435,6 +518,7 @@ This option is currently supported by: - Render.com (RND): Uses Blueprint's `fromService` syntax - DigitalOcean App Platform (DOP): Uses direct service names +- Kubernetes Helm Charts (HELM): Uses Kubernetes DNS service discovery Example: diff --git a/docs/docker-to-iac/multi-file-configuration.md b/docs/docker-to-iac/multi-file-configuration.md index 9e15094..52e0eb3 100644 --- a/docs/docker-to-iac/multi-file-configuration.md +++ b/docs/docker-to-iac/multi-file-configuration.md @@ -56,6 +56,29 @@ mychart/ └── _helpers.tpl # Template helpers ``` +The docker-to-iac module now includes a Helm parser that generates this exact structure when translating Docker configurations to Helm Charts: + +```javascript +const result = translate(dockerComposeContent, { + source: 'compose', + target: 'HELM', + templateFormat: 'yaml' +}); + +// Result contains all files needed for a complete Helm Chart +console.log(Object.keys(result.files)); +// [ +// 'Chart.yaml', +// 'values.yaml', +// 'templates/deployment.yaml', +// 'templates/service.yaml', +// 'templates/configmap.yaml', +// 'templates/secret.yaml', +// 'templates/NOTES.txt', +// 'templates/_helpers.tpl' +// ] +``` + With the multi-file support, a Helm Chart parser configuration might look like: ```typescript diff --git a/docs/docker-to-iac/parser/helm.md b/docs/docker-to-iac/parser/helm.md new file mode 100644 index 0000000..2b13ff5 --- /dev/null +++ b/docs/docker-to-iac/parser/helm.md @@ -0,0 +1,210 @@ +--- +description: Translate Docker Compose files into Kubernetes Helm Charts with DeployStack docker-to-iac module +menuTitle: Helm +--- + +# Helm - Parser Full Documentation + +The parser for Helm translates Docker configurations into Kubernetes Helm Charts. The parser logic can be found in GitHub inside the [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/helm.ts). + +## Parser language abbreviation for API + +- `languageAbbreviation`: `HELM`. + +## Prerequisite to deploy Helm Charts + +To deploy the generated Helm Charts, you need: + +- A Kubernetes cluster (local or cloud-based) +- Helm CLI installed (version 3.x recommended) +- Appropriate RBAC permissions to deploy resources in your target namespace + +### Kubernetes Resources + +The generated Helm Chart creates the following Kubernetes resources for each service in your Docker configuration: + +- **Deployments**: Container specifications, replica count, resource limits +- **Services**: Network access to your pods with appropriate ports +- **ConfigMaps**: Non-sensitive environment variables +- **Secrets**: Sensitive environment variables (passwords, tokens, etc.) + +### Database Support + +For database services, the parser leverages Helm's dependency management to incorporate official Bitnami charts: + +- **MySQL/MariaDB**: Uses Bitnami's MySQL/MariaDB chart +- **PostgreSQL**: Uses Bitnami's PostgreSQL chart +- **Redis**: Uses Bitnami's Redis chart +- **MongoDB**: Uses Bitnami's MongoDB chart + +Each database dependency is configured with appropriate defaults and includes persistent storage for data. + +## Default output format + +- The default output format for this parser: `YAML`. + +## File Configuration + +The Helm parser generates a complete Helm Chart directory structure: + +- `Chart.yaml` - The main chart definition with metadata and dependencies +- `values.yaml` - Configuration values that can be customized at deployment time +- `templates/` - Directory containing Kubernetes YAML templates: + - `deployment.yaml` - Deployment specifications for each service + - `service.yaml` - Service definitions for network access + - `configmap.yaml` - ConfigMap for non-sensitive environment variables + - `secret.yaml` - Secret for sensitive environment variables + - `_helpers.tpl` - Helper functions for template generation + - `NOTES.txt` - Usage instructions displayed after installation + +This multi-file approach follows the standard Helm Chart structure and allows for maximum flexibility when deploying to Kubernetes. + +## Supported Docker Compose Variables + +This parser supports the following Docker Compose variables: + +- `image` +- `environment` +- `ports` +- `command` +- `volumes` + +::content-alert{type="note"} +The parser automatically detects sensitive environment variables (containing keywords like "password", "secret", "key", "token", or "auth") and places them in Kubernetes Secrets instead of ConfigMaps. +:: + +## Volume Support + +The parser supports Docker volume mappings by converting them to Kubernetes volume mounts: + +- Each volume is converted to a hostPath volume by default +- Volume names are sanitized to conform to Kubernetes naming conventions +- For production use, you should modify the generated templates to use more appropriate volume types (PersistentVolumeClaims, etc.) + +## Database Integration + +When a database service is detected (MySQL, PostgreSQL, Redis, MongoDB), the parser: + +1. Adds the corresponding Bitnami Helm chart as a dependency in `Chart.yaml` +2. Configures database settings in `values.yaml` +3. Maps environment variables to the expected format for the database chart +4. Sets up appropriate persistence configurations + +### Example Database Configuration + +For a PostgreSQL database in your Docker Compose file: + +```yaml +services: + db: + image: postgres:13 + environment: + POSTGRES_USER: myuser + POSTGRES_PASSWORD: mypassword + POSTGRES_DB: myapp +``` + +The parser will create: + +```yaml +# In Chart.yaml +dependencies: + - name: db + repository: https://charts.bitnami.com/bitnami + version: ^12.0.0 + condition: dependencies.db.enabled + +# In values.yaml +dependencies: + db: + enabled: true + auth: + postgres: + password: mypassword + database: myapp + username: myuser + password: mypassword + primary: + service: + ports: + postgresql: 5432 + persistence: + enabled: true + size: 8Gi +``` + +## Service Connections + +The parser supports service-to-service connections by leveraging Kubernetes DNS for service discovery. When a service refers to another service in an environment variable, the parser automatically configures the appropriate DNS references. + +For example, if your `app` service connects to a `db` service: + +```yaml +# Docker Compose +services: + app: + image: myapp + environment: + DATABASE_URL: postgresql://postgres:password@db:5432/mydb + + db: + image: postgres + environment: + POSTGRES_PASSWORD: password + POSTGRES_DB: mydb +``` + +The parser will create: + +```yaml +# In ConfigMap template +data: + DATABASE_URL: {{ include "deploystack.serviceReference" (dict "service" (index $.Values.services "db") "serviceKey" "db") }} +``` + +Which resolves to the Kubernetes DNS name: `db.{{ .Release.Namespace }}.svc.cluster.local:5432` + +## Multi Services Support + +Multi `services` support for Helm: **yes** + +Helm Charts are designed to handle multiple services and dependencies in a single deployment, making them ideal for complex applications. The parser transforms all services from your Docker Compose file into corresponding Kubernetes resources. + +Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support.md). + +## Deployment Instructions + +To deploy the generated Helm Chart: + +1. Navigate to the directory containing the generated chart +2. Install dependencies: + + ```bash + helm dependency update + ``` + +3. Install the chart: + + ```bash + helm install my-release . + ``` + +4. For custom configurations: + + ```bash + helm install my-release . --set services.app.replicaCount=2 + ``` + +## Production Considerations + +For production deployments, consider the following modifications to the generated chart: + +1. Replace hostPath volumes with appropriate persistent volume claims +2. Adjust resource limits in `values.yaml` +3. Configure proper ingress settings for external access +4. Enable and configure horizontal pod autoscaling +5. Set up proper liveness and readiness probes + +::content-alert{type="important"} +The generated Helm Chart is a starting point that you should review and customize to match your production requirements and security best practices. +:: diff --git a/docs/docker-to-iac/parser/index.md b/docs/docker-to-iac/parser/index.md index a5af3ea..65190e9 100644 --- a/docs/docker-to-iac/parser/index.md +++ b/docs/docker-to-iac/parser/index.md @@ -10,3 +10,4 @@ Here you can find the list of available [parsers](/docs/docker-to-iac/parser-exp - [AWS CloudFormation](/docs/docker-to-iac/parser/aws-cloudformation.md) - [Render.com](/docs/docker-to-iac/parser/render.com.md) - [DigitalOcean](/docs/docker-to-iac/parser/digitalocean.md) +- [Helm (Kubernetes)](/docs/docker-to-iac/parser/helm.md) diff --git a/docs/docker-to-iac/publishing-to-npm.md b/docs/docker-to-iac/publishing-to-npm.md index 8352ac2..ef7f45a 100644 --- a/docs/docker-to-iac/publishing-to-npm.md +++ b/docs/docker-to-iac/publishing-to-npm.md @@ -5,7 +5,7 @@ menuTitle: Publishing to NPM # Publishing docker-to-iac module to NPM -The docker-to-iac module is published to the @deploystack organization on NPM. The publishing process is automated through GitHub Actions and follows a conventional commit-based workflow. +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) ## Release Process Overview diff --git a/docs/docker-to-iac/supported-registries.md b/docs/docker-to-iac/supported-registries.md index abc2c91..34f039b 100644 --- a/docs/docker-to-iac/supported-registries.md +++ b/docs/docker-to-iac/supported-registries.md @@ -80,3 +80,4 @@ Here's how different registry types are handled: - If no tag is specified, `latest` is used as the default tag - The module preserves the original registry URL format for custom registries - SHA256 digests are supported for all registry types +- All supported registries work with all parsers, including AWS CloudFormation, Render.com, DigitalOcean App Platform, and Kubernetes Helm Charts diff --git a/docs/index.md b/docs/index.md index 59ce08b..ba41c01 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,7 @@ menuTitle: DeployStack Documentation # DeployStack Documentation -DeployStack converts your **Docker configurations** into **Infrastructure as Code** (IaC) templates for multiple cloud providers. Whether you have a docker-compose.yml file or docker run commands, it generates the necessary AWS CloudFormation, Render.com Blueprint, or DigitalOcean specifications for example. This lets you and your users deploy the same application consistently across different cloud platforms using their native deployment mechanisms, **without needing to manually create** each provider's infrastructure. +DeployStack converts your **Docker configurations** into **Infrastructure as Code** (IaC) templates for multiple cloud providers. Whether you have a docker-compose.yml file or docker run commands, it generates the necessary AWS CloudFormation, Render.com Blueprint, DigitalOcean specifications, or Kubernetes Helm charts for example. This lets you and your users deploy the same application consistently across different cloud platforms using their native deployment mechanisms, **without needing to manually create** each provider's infrastructure. ## Get Started @@ -30,6 +30,7 @@ DeployStack generates infrastructure templates for major cloud providers, each o !card-image[AWS]{title="AWS" link="/docs/docker-to-iac/parser/aws-cloudformation" src="/img/deploy/aws.svg" width=47 height=28} !card-image[DigitalOcean]{title="DigitalOcean" link="/docs/docker-to-iac/parser/digitalocean" src="/img/deploy/digitalocean.svg" width=56 height=28} !card-image[Render.com]{title="Render.com" link="/docs/docker-to-iac/parser/render.com" src="/img/deploy/render.svg" width=130 height=28} +!card-image[Helm]{title="Helm" link="/docs/docker-to-iac/parser/helm" src="/img/deploy/helm.svg" width=47 height=47} ::: ### DeployStack Ecosystem