deployment

Deployment Skill

Unified deployment configuration generation capability, focused onconfiguration generation. The generated Makefile contains all deployment logic and is the primary execution interface.

Scenario: configuration generation

Generate deployment infrastructure:

• Makefile containing deployment targets
• Dockerfile template
• Docker Compose file for each environment
• Environment configuration file (.deploy.env.common、.deploy.env.<env>）

Usage

# 基础配置生成
python3 skills/deployment/scripts/config.py \
  --app-name my-app \
  --registry-host registry.example.com \
  --remote-user deploy \
  --remote-host 192.168.1.100 \
  --remote-port 2222

# 使用 JSON profile
python3 skills/deployment/scripts/config.py \
  --from-json deploy-profile.json

# 完整示例（所有环境）
python3 skills/deployment/scripts/config.py \
  --app-name my-app \
  --version v1.0.0 \
  --env-mode test \
  --registry-host registry.example.com \
  --remote-user deploy \
  --remote-host 192.168.1.100 \
  --remote-port 2222 \
  --test-remote-host test.example.com \
  --test-remote-port 22 \
  --prod-registry-host registry.prod.example.com \
  --prod-remote-user deploy-prod \
  --prod-remote-host prod.example.com \
  --prod-remote-port 2222

Generated files

.
├── Makefile                          # 主要部署接口
├── Dockerfile                        # 容器构建模板
├── docker-compose.local.yaml         # 本地开发
├── docker-compose.test.yaml          # 测试环境
├── docker-compose.yaml               # 生产环境
├── .deploy.env.common                # 共享配置
├── .deploy.env.test                  # 测试环境覆盖
└── .deploy.env.prod                  # 生产环境覆盖

Generated Makefile targets

Run config.py , the Makefile provides the following targets:

make check-config      # 验证配置
make test              # 运行本地 compose 烟雾测试
make build             # 通过 buildx 构建 amd64 镜像
make build-arm         # 从 monorepo 根目录构建镜像
make save              # 保存镜像 tarball
make tag               # 使用 registry 路径标记镜像
make push              # 推送镜像到 registry
make remote-pull       # 在远程主机上拉取镜像
make remote-clean      # 清理远程悬空镜像
make local-clean       # 清理本地镜像
make push-compose-file # 上传 compose 文件到远程主机
make remote-deploy     # 在远程主机上部署
make remote-status     # 检查远程 compose 状态
make remote-logs       # 追踪远程主机最近的日志
make help              # 显示帮助

Usage after generation

# 部署到测试环境
make ENV_MODE=test remote-deploy

# 部署到生产环境
make ENV_MODE=prod remote-deploy VERSION=v1.0.0

# 预演（dry-run）
make -n ENV_MODE=test remote-deploy

# 显示帮助
make help

---

Configuration priority

Priority order:

1. CLI parameters
2. Environment variables
3. JSON profile
4. Internal default values

JSON Profile (optional)

{
  "app_name": "my-app",
  "version": "latest",
  "env_mode": "test",
  "use_sudo": true,
  "environments": {
    "test": {
      "registry_host": "registry.test.example.com",
      "remote_host": "test.example.com",
      "remote_port": 22
    },
    "prod": {
      "registry_host": "registry.prod.example.com",
      "remote_host": "prod.example.com",
      "remote_port": 2222
    }
  }
}

With python3 skills/deployment/scripts/config.py --from-json deploy-profile.json used together.

---

Architecture

skills/deployment/
├── SKILL.md              # 本文件
├── scripts/
│   ├── config.py         # 配置生成器
│   ├── common.py         # 共享工具
│   └── profile.py        # Profile 处理
└── references/
    ├── config.md         # 配置生成文档
    └── config-profile.md # Profile 配置文档

Design principles

1. Makefile first: the generated Makefile is the primary interface
2. Configuration as code: all deployment logic is in the generated files
3. Scripts as generators: Python scripts generate infrastructure
4. Scenario independence: each environment scenario can be executed independently