graviton/compose-transpiler

compose transpiler

https://img.shields.io/travis/libgraviton/compose-transpiler.svg](https://travis-ci.org/libgraviton/compose-transpiler) https://img.shields.io/docker/pulls/graviton/compose-transpiler.svg](https://hub.docker.com/r/graviton/compose-transpiler/) https://img.shields.io/docker/stars/graviton/compose-transpiler.svg](https://hub.docker.com/r/graviton/compose-transpiler/) https://img.shields.io/docker/automated/graviton/compose-transpiler.svg](https://hub.docker.com/r/graviton/compose-transpiler/)

镜像概述和主要用途

compose transpiler是一个小型脚本，用于从模板转换YAML结构（如Docker Compose文件）。其主要用途是在具有多个不同阶段和/或租户的环境中，减少Docker Compose和/或stack文件等YAML结构的重复配置。在这类环境中，许多配置基本相同但因租户/阶段而异，该脚本可避免重复劳动和配置错误，通过"配置文件"（可继承/扩展其他配置文件）和模板生成完全有效的Docker Compose/Stack文件（适用于Docker Swarm v12.0+）。

核心功能和特性

• 模板化配置：通过Twig模板语言处理YAML文件，支持动态内容生成
• 配置文件继承：配置文件可继承其他配置文件，并支持取消父配置中的特定路径
• 组件化设计：将配置拆分为基础模板、组件和混合片段，提高复用性
• 暴露服务配置：通过特殊模板实现服务暴露配置，自动生成代理容器配置
• 变量传递：支持向模板传递任意变量，增强配置灵活性

使用场景和适用范围

• 多租户部署环境，需要为不同租户生成相似但略有差异的Docker Compose配置
• 多阶段部署（如开发、测试、生产环境），需要维护基本一致但有环境特定参数的配置
• 大型项目中存在大量重复服务配置，需要通过模板统一管理的场景

详细使用方法和配置说明

前提条件

需创建以下基本模板目录结构：

./_templates
./_templates/base // 存放头部和底部模板
./_templates/components // 存放组件模板
./_templates/mixins // 存放混合片段模板

其中，./_templates为模板根目录（$templateDir）。所有以.tmpl.yml结尾的文件均被视为Twig模板，可包含Twig模板语言结构。

基本使用方法

步骤1：创建模板文件

• ./_templates/base/header.tmpl.yml（头部模板）：

  yaml
  version: 3.2
  

• ./_templates/base/footer.tmpl.yml（底部模板）：

  yaml
  networks:
    default:
      driver: overlay
  

• ./_templates/components/redis.tmpl.yml（组件模板）：

  yaml
  image: 'docker.xuanyuan.run/redis:latest'
  environment:
    VAR1=a
  

步骤2：创建配置文件

创建./myapp.yml作为配置文件：

yaml
components:
  redis:

步骤3：执行转换

通过代码执行转换：

php
$t = new \Graviton\ComposeTranspiler\Transpiler(__DIR__.'/_templates');
$t->transpile("./myapp.yml", "./transpiled.yml");

生成结果：./transpiled.yml

yaml
version: 3.2
services:
  redis:
    image: 'docker.xuanyuan.run/redis:latest'
    environment:
      VAR1=a
networks:
  default:
    driver: overlay    

混合片段（Mixins）

混合片段是可添加到任何组件的小型配置片段，适用于多个组件共享的配置（如通用环境变量）。

步骤1：创建混合片段模板

./_templates/mixins/sentry-dsn.tmpl.yml：

yaml
environment:
  SENTRY_DSN="http://mysentry/urlurlurl"

步骤2：在配置文件中引用混合片段

./myapp.yml：

yaml
components:
  redis:
    mixins:
      sentry-dsn:

生成结果：

yaml
version: 3.2
services:
  redis:
    image: 'docker.xuanyuan.run/redis:latest'
    environment:
      VAR1=a
      SENTRY_DSN="http://mysentry/urlurlurl"
networks:
  default:
    driver: overlay    

服务暴露（Exposing）

通过特殊的_expose.tmpl.yml模板，可为需要通过独立容器（如Nginx代理）暴露的组件自动生成暴露配置。

步骤1：创建暴露模板

./_templates/components/_expose.tmpl.yml：

yaml
image: 'docker.xuanyuan.run/my-nginx:latest'
ports:
  - {{ exposePort }}:9080
environment:
  - UPSTREAM_URL={{ upstreamUrl}}

步骤2：在配置文件中添加暴露配置

./myapp.yml：

yaml
components:
  redis:
    expose:
      exposePort: 80
      upstreamUrl: http://redis:9000
    mixins:
      sentry-dsn:

生成结果：

yaml
version: 3.2
services:
  redis:
    image: 'docker.xuanyuan.run/redis:latest'
    environment:
      VAR1=a
      SENTRY_DSN="http://mysentry/urlurlurl"
  redis-expose:
    image: 'docker.xuanyuan.run/my-nginx:latest'
    ports:
      - 80:9080
    environment:
      - UPSTREAM_URL=http://redis:9000 
networks:
  default:
    driver: overlay

向模板传递变量

可在配置文件中为组件定义任意变量，这些变量将作为Twig变量在组件模板中可用。

配置文件示例：./myapp.yml

yaml
components:
  redis:
    myVar: 1
    whatEverValue: whynot

此时，myVar和whatEverValue可在redis.tmpl.yml模板中通过Twig语法访问。

配置文件继承

配置文件可通过_inheritance键继承其他配置文件，并支持取消父配置中的特定路径。

基础配置文件：./myapp.yml

yaml
components:
  redis:
  mysql:

继承并扩展配置文件：./myapp-other.yml

yaml
_inheritance:
  extends: ./myapp.yml
components:
  postgres:

生成的合并配置：

yaml
components:
  redis:
  mysql:
  postgres:

继承并取消父配置路径：./myapp-other.yml

yaml
_inheritance:
  extends: ./myapp.yml
  unsets:
    - "components.mysql"
components:
  postgres:

生成的配置：

yaml
components:
  redis:
  postgres:

注：取消路径仅支持通过点表示法指定的简单路径，不支持复杂操作。