dpmrb 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d408ee6f24c0e503159587c35ef634821cba4143ee0a4bde49c0497636cde125
-  data.tar.gz: 1de01b1572bcc96575e7f2716ac78fefc5e38f87da9ed59e25a8d27117861e79
+  metadata.gz: 7071062b1142b4ccb9003d85dba16f38167dcb8e1338a39f0d815c6177750bf6
+  data.tar.gz: 286ac526db640e294e52a35f0939e2840ac8dd124979187e343d9f5c1a0f1c6b
 SHA512:
-  metadata.gz: 14f44aa24ca13e24032199766ddfc0ee90e25e8ffd873cba6d53ecffbc751def9a01cedd4c9e52457b64a44ccff48d65da6e30e20d9cbd3e1d23595708a760ed
-  data.tar.gz: 0cf758ea38f95aea2cd0ce13d3ca300f0936d5c751b1fc957b993395d3f020ecef5850f78ad39c9135f587dd88b03b993cfe612f2819a3e700ebc5703702e0bf
+  metadata.gz: d1afcdbab71d64680d3e350999585526dab02ce1fa5dcfc36f5083f88c92780148c50aa8e7ac393cb62f519f4ccf05d37bfde6cec75ea76ca22ee02f797a1533
+  data.tar.gz: eb3fcc41aa0cf974809a916a7f5c3d0d11f91342476276a92fc92e0ad895e94e519476d54528c16d05e1b202852c8dfd11b513f937c070a0e3d0210345878087

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dpmrb (0.2.1)
+    dpmrb (0.2.2)
       activesupport (~> 6.x)
 
 GEM

data/README.en-US.md

@@ -2,10 +2,15 @@
 
 # DPM
 
-Docker Package Manager, makes using your containers as easy as package managers (`apt`, `yml`, `brew`).
+Docker Package Manager, makes using your Docker as easy as package managers (`apt`, `yum`, `brew`).
 
 ## Installation
 
+Dependency:
+- Docker
+- Ruby >= 2.6
+
+Install command:
 ```bash
 gem install dpmrb
 ```
@@ -13,29 +18,59 @@ gem install dpmrb
 ## Usage
 
 ```bash
-dpm help                       # Show help
-dpm list                       # docker ps --filter "name=dpm-"
-dpm start mysql                # docker run --name=dpm-mysql -d --rm -p 3306:3306 -e MYSQL_ALLOW_EMPTY_PASSWORD=yes ...
-dpm stop mysql                 # docker stop dpm-mysql
-dpm status mysql               # docker ps --filter "name=dpm-mysql"
-dpm start elasticsearch:7.10.2 # docker run --name=dpm-elasticsearch-7.10.2 -d --rm -p 9200:9200 -e discovery.type=single-node ...
-dpm start mysql:5.7            # docker run --name=dpm-mysql-5.7 -d --rm -p 3306:3306 -e MYSQL_ALLOW_EMPTY_PASSWORD=yes ...
+dpm pacakges                   # List all supported packages
+dpm start mysql                # Start the package `mysql` by the config `packages/mysql.yml`
+dpm stop mysql                 # Stop the package `mysql`
+dpm status mysql               # Show the status of the package `mysql`
+dpm help                       # Get help to show all the features
 ```
 
-## Development
+## Package Config
+
+DPM supports two types of package configs:
+1. The "System Package Config" in the directory `packages/` of repo
+2. The "User Package Config" in the directory `~/.dpm/packages/` of user
+
+### System Package Config
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+The goal of "System Package Config" is to make a Docker service run the same as the natively installed one. Take MySQL as an example:
+- After the native MySQL is installed and run, it will bind port 3306 by default, so our MySQL package configuration should also expose the service port to the host by default
+- After the native MySQL is installed, there are fixed configuration directories and log directories, so our MySQL package configuration must also map these directories in the container to fixed directories
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### User Package Config
 
-## Contributing
+"User Package Config" has the following usage scenarios:
+1. If the default package configuration of DPM is unreasonable and you want to change it, you can use "User Package Config" to debug and view the results, and then submit MR to the repo.
+2. DPM does not provide the package you need, you need to add your own package configuration. (Contributions of your new package configuration to DPM are welcome).
+3. DPM default package configuration is not suitable for local environment, need to override "System Package Config". For example, if I need to run two MySQL services locally, then I need to change the port of one of the services to the other to avoid conflicts.
+
+#### Add User Package Config
+
+"User Package Config" provides the following commands for quick creation:
+```bash
+dpm configure PACKAGE
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/songhuangcn/dpm. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/songhuangcn/dpm/blob/main/CODE_OF_CONDUCT.md).
+The function of this command is to add a new package configuration file `PACKAGE.yml` under the user directory `~/.dpm/`.
+If the package already exists in the "system package configuration", the contents will be initialized into this file.
 
-## License
+**Note:** If the PACKAGE parameter is `package`, the "Global Package Config" `config/package.yml` is configured, and the configuration here will be merged into all packages.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Related Tools
+
+- [Visual Studio Code Plugin](https://marketplace.visualstudio.com/items?itemName=UoooBarry.dpm-vscode)
+
+## Development
+
+### Setup environment
+
+```bash
+git clone git@github.com:songhuangcn/dpm.git
+cd dpm
+bin/setup # Need Ruby >= 2.6
+```
 
-## Code of Conduct
+### Development Skills
 
-Everyone interacting in the DPM project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/songhuangcn/dpm/blob/main/CODE_OF_CONDUCT.md).
+- Adding ENV `DEBUG` to all commands will show detailed error stack to help locate the problem
+- After development, use the command `bin/check` to check code specifications and tests, and resolve some CI failures in advance

data/README.md

@@ -2,10 +2,15 @@
 
 # DPM
 
-Docker Package Manager, 让你的容器用起来跟包管理器（`apt`, `yml`, `brew`）一样简单。
+Docker Package Manager, 让你的 Docker 用起来跟包管理器（`apt`, `yum`, `brew`）一样简单。
 
 ## 安装
 
+依赖：
+- Docker
+- Ruby >= 2.6
+
+安装命令：
 ```bash
 gem install dpmrb
 ```
@@ -13,91 +18,58 @@ gem install dpmrb
 ## 使用
 
 ```bash
-dpm help                       # Show help
-dpm list                       # docker ps --filter "name=dpm-"
-dpm start mysql                # docker run --name=dpm-mysql -d --rm -p 3306:3306 -e MYSQL_ALLOW_EMPTY_PASSWORD=yes ...
-dpm stop mysql                 # docker stop dpm-mysql
-dpm status mysql               # docker ps --filter "name=dpm-mysql"
-dpm start elasticsearch:7.10.2 # docker run --name=dpm-elasticsearch-7.10.2 -d --rm -p 9200:9200 -e discovery.type=single-node ...
-dpm start mysql:5.7            # docker run --name=dpm-mysql-5.7 -d --rm -p 3306:3306 -e MYSQL_ALLOW_EMPTY_PASSWORD=yes ...
+dpm pacakges                   # 列出所有支持的包
+dpm start mysql                # 通过配置 `packages/mysql.yml` 运行 `mysql` 包
+dpm stop mysql                 # 停止运行 `mysql` 包
+dpm status mysql               # 展示 `mysql` 包的运行状态
+dpm help                       # 展示帮助，查看所有功能
 ```
 
-## 为项目添加新包
-
-DPM 跟 [Homebrew](https://brew.sh/) 一样，需要完善更多的包配置，欢迎为 `packages` 目录添加你需要的包配置。
+## 包配置
 
-### 配置级别
+DPM 支持两种包配置：
+1. 项目 repo 目录 `packages/` 的 "系统包配置"
+1. 用户目录 `~/.dpm/packages` 的 "用户包配置"
 
-容器配置都是通用的 YAML 格式，有三个级别：
+### 系统包配置
 
-1. 默认级别：`packages/default.yml`
-1. 包级别：`packages/PACKAGE/default.yml`
-1. 版本级别：`packages/PACKAGE/tag-TAG.yml`
+"系统包配置" 目标是让一个 Docker 服务跑起来跟原生安装的软件一致，拿 MySQL 来举例：
+- 原生软件 MySQL 安装好运行后，会默认绑定好 3306 端口，那我们的 MySQL 包配置就要做到默认也暴露该服务端口到主机
+- 原生软件 MySQL 安装好后，有固定的配置目录和日志目录，那我们的 MySQL 包配置就要做到也将容器里的这些目录映射到固定的目录
 
-配置是合并机制，如果一个包没有自定义配置，他就会根据默认级别配置跑起来。
+### 用户包配置
 
-### 配置示例
+"用户包配置" 有以下使用场景：
+1. DPM 默认包配置不合理想更改，可以先用 "用户包配置" 调试查看结果，然后给 repo 提 MR。
+2. DPM 没有提供你需要的包，需要添加自己包配置。（欢迎给 DPM 贡献你的新包配置）。
+3. DPM 默认包配置不适合本地环境，需要覆盖 "系统包配置"。比如我本地需要跑两个 MySQL 服务，那我就需要把其中一个服务的端口改成其他避免冲突。
 
-例如有配置如下：
+#### 添加用户包配置
 
-1. `packages/default.yml`：
-    ```yml
-    run_options:
-      rm: true
-      d: true
-    ```
-1. `packages/mysql/default.yml`：
-    ```yml
-    run_options:
-      e: "MYSQL_ALLOW_EMPTY_PASSWORD=yes"
-      p: "3306:3306"
-    ```
-1. `packages/mysql/tag-5.7.yml`：
-    ```yml
-    run_options:
-      p: "3307:3307"
-    ```
+"用户包配置" 提供了以下命令快速创建：
+```bash
+dpm configure PACKAGE
+```
 
-则最终这些包配置的启动命令为：
+该命令功能就是在用户目录 `~/.dpm/` 下添加一个新的包配置文件 `PACKAGE.yml`。如果该包在 "系统包配置" 已经存在，则会将内容初始化到该文件里。
 
-- `mysql:5.7` 的配置：
-    ```bash
-    docker run --rm -d -p 3307:3307 -e MYSQL_ALLOW_EMPTY_PASSWORD=yes mysql:5.7
-    ```
-- `mysql` 的配置：
-    ```bash
-    docker run --rm -d -p 3306:3306 -e MYSQL_ALLOW_EMPTY_PASSWORD=yes mysql
-    ```
-- `not-exist-pkg` 的配置：
-    ```bash
-    docker run --rm -d not-exist-pkg
-    ```
+**注意：** 如果 PACKAGE 参数为 `package`，则配置的是 "全局系统包配置" `config/package.yml`，这里的配置会合并到所有包里。
 
-### 其他配置
+## 相关工具
 
-有一些其他配置项，例如 `image`：
+- [Visual Studio Code 插件](https://marketplace.visualstudio.com/items?itemName=UoooBarry.dpm-vscode)
 
-`packages/elasticsearch/default.yml`
-```yml
-image: "docker.elastic.co/elasticsearch/elasticsearch"
-```
+## 开发调试
 
-则 `elasticsearch` 包的镜像将不在按约定自动计算，而是变成了：
+### 搭建环境
 
 ```bash
-docker.elastic.co/elasticsearch/elasticsearch
+git clone git@github.com:songhuangcn/dpm.git
+cd dpm
+bin/setup # 需要 Ruby >= 2.6
 ```
 
-还有一些配置，例如：`args`，这个是传入到容器的参数，例如有配置文件 `packages/mysql/default.yml`：
+### 开发技巧
 
-```yml
-args:
-  character-set-server: "utf8mb4"
-  collation-server: "utf8mb4_unicode_ci"
-```
-
-则所有版本的 `mysql` 包将会多这两个启动参数：
-
-```bash
-docker run mysql --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
-```
+- 给所有命令添加 ENV `DEBUG` 会展示详细错误堆栈，帮助定位问题
+- 开发完后，请使用命令 `bin/check` 检查代码规范和测试，提前解决一些 CI 失败的情况

data/bin/dpm

@@ -5,6 +5,7 @@ require_relative "../lib/dpm"
 begin
   DPM.call!(ARGV)
 rescue => exception
+  raise if ENV["DEBUG"]
   puts "Fatal error: #{exception.message}"
   exit 1
 end

data/config/config.template.yml

@@ -0,0 +1,30 @@
+# .base: &base
+#   {}  # Base config, like: `image_name`, `tag_name`
+# .run_options: &run_options
+#   {} # Docker run options, like: `p`, `publish`, `v`, `volume`
+# .run_args: &run_args
+#   {} #Docker run args, like: `character-set-server`
+#
+# latest:
+#   base:
+#     <<: *base
+#   run_options:
+#     <<: *run_options
+#   run_args:
+#     <<: *run_args
+#
+# tag1:
+#   base:
+#     <<: *base
+#   run_options:
+#     <<: *run_options
+#   run_args:
+#     <<: *run_args
+#
+# tag2:
+#   base:
+#     <<: *base
+#   run_options:
+#     <<: *run_options
+#   run_args:
+#     <<: *run_args

data/dpm.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email = ["songhuangcn@gmail.com"]
 
   spec.summary = "Docker Package Manager."
-  spec.description = "Makes using your containers as easy as package managers (`apt`, `yml`, `brew`)."
+  spec.description = "Docker Package Manager. Makes using your containers as easy as package managers (`apt`, `yum`, `brew`)."
   spec.homepage = "https://github.com/songhuangcn/dpm"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.6.0"

data/lib/dpm/options.rb

@@ -2,9 +2,9 @@ require "optparse"
 
 module DPM
   class Options
-    PACKAGE_COMMANDS = %w[tags status start stop restart].freeze
+    PACKAGE_COMMANDS = %w[tags status start stop restart configure].freeze
     PACKAGE_REGEX = /\A[\w.\-:]+\z/.freeze
-    UNPACKAGE_COMMANDS = %w[list packages].freeze
+    UNPACKAGE_COMMANDS = %w[list packages cleanup].freeze
 
     attr_accessor :argv, :dry_run, :parser, :command, :package
 
@@ -23,15 +23,12 @@ module DPM
 
         parser.banner = "Usage: dpm [options] [COMMAND] [PACKAGE]"
         parser.separator ""
-        parser.separator "Specific options:"
+        parser.separator "Options:"
 
-        parser.on("-d", "--dry-run", "Don't actually run anything, just print") do |v|
+        parser.on("-d", "--dry-run", "Don't actually run Docker command, just print") do |v|
           self.dry_run = v
         end
 
-        parser.separator ""
-        parser.separator "Common options:"
-
         parser.on_tail("-h", "--help", "Show the help") do
           puts help_text
           exit
@@ -57,11 +54,13 @@ module DPM
             version                          Show the version
             packages                         List supported packages
             list                             List running packages
+            cleanup                          Cleanup useless data
             tags PACKAGE                     List supported tags of a package
             status PACKAGE                   Get the status of a package
             start PACKAGE                    Start a package
             stop PACKAGE                     Stop a package
             restart PACKAGE                  Restart a package
+            configure PACKAGE                Configure a package in the user-level, including configure a new package
 
         See more at https://github.com/songhuangcn/dpm
       EOF

data/lib/dpm/runner.rb

@@ -8,7 +8,7 @@ module DPM
     CONTAINER_NAME_PREFIX = "dpm-"
     BASH_COLOR_GRAY = "\033[0;37m"
     BASH_COLOR_NONE = "\033[0m"
-    DOCKER_COMMANDS = %w[list status start stop restart].freeze
+    DOCKER_COMMANDS = %w[list status start stop restart cleanup].freeze
 
     attr_accessor :options
 
@@ -28,6 +28,8 @@ module DPM
         call_packages!
       when "tags"
         call_tags!
+      when "configure"
+        call_configure!
       end
     end
 
@@ -45,6 +47,8 @@ module DPM
         "docker stop #{container_name}"
       when "restart"
         "dpm stop #{options.package} && dpm start #{options.package}"
+      when "cleanup"
+        "docker system prune --force"
       else
         raise "Not implemented command: `#{command}`"
       end
@@ -68,6 +72,24 @@ module DPM
       puts tags
     end
 
+    def call_configure!
+      raise Error, "Need set $EDITOR" unless ENV["EDITOR"]
+
+      config_dir = package_name == "package" ? "config" : "packages"
+      user_config = File.join(HOME, config_dir, "#{package_name}.yml")
+      unless File.exist?(user_config)
+        system_config = File.join(ROOT, config_dir, "#{package_name}.yml")
+        init_data = if File.exist?(system_config)
+          File.read(system_config)
+        else
+          File.read(File.join(ROOT, "config", "config.template.yml"))
+        end
+        File.write(user_config, init_data)
+      end
+
+      `#{ENV["EDITOR"]} #{user_config}`
+    end
+
     def bash_color(text)
       "#{BASH_COLOR_GRAY}#{text}#{BASH_COLOR_NONE}"
     end
@@ -137,13 +159,13 @@ module DPM
     end
 
     def package_config_yaml
-      @package_config_yaml ||= load_yaml(File.join(ROOT, "packages", "#{package_name}.yml"))
+      @package_config_yaml ||= load_yaml(File.join("packages", "#{package_name}.yml"))
     rescue Errno::ENOENT
       raise Error, "Package `#{package_name}` not support"
     end
 
     def default_config
-      @default_config ||= load_yaml(File.join(ROOT, "config", "package.yml"))
+      @default_config ||= load_yaml(File.join("config", "package.yml"))
     end
 
     def package_name
@@ -159,7 +181,9 @@ module DPM
     end
 
     def load_yaml(file_path)
-      text = File.read(file_path)
+      user_path = File.join(HOME, file_path)
+      system_path = File.join(ROOT, file_path)
+      text = File.exist?(user_path) ? File.read(user_path) : File.read(system_path)
       data = ERB.new(text).result(binding)
       yaml = YAML.safe_load(data, aliases: true).tap do |yaml|
         raise Error, "Config need to be a hash yaml: #{file_path}" unless yaml.is_a?(Hash)

data/lib/dpm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DPM
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dpmrb
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Song Huang
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-18 00:00:00.000000000 Z
+date: 2022-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,8 +24,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 6.x
-description: Makes using your containers as easy as package managers (`apt`, `yml`,
-  `brew`).
+description: Docker Package Manager. Makes using your containers as easy as package
+  managers (`apt`, `yum`, `brew`).
 email:
 - songhuangcn@gmail.com
 executables:
@@ -43,6 +43,7 @@ files:
 - README.md
 - Rakefile
 - bin/dpm
+- config/config.template.yml
 - config/package.yml
 - dpm.gemspec
 - lib/dpm.rb
@@ -77,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.20
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Docker Package Manager.
 test_files: []