{"id":15512851,"url":"https://github.com/amancevice/rumrunner","last_synced_at":"2025-03-16T08:32:07.408Z","repository":{"id":35024352,"uuid":"195823633","full_name":"amancevice/rumrunner","owner":"amancevice","description":"Rake-based utility for building multi-stage Dockerfiles.","archived":false,"fork":false,"pushed_at":"2024-03-10T14:45:15.000Z","size":1735,"stargazers_count":34,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-27T05:51:23.511Z","etag":null,"topics":["cli","docker","dsl","multi-stage-dockerfiles","rake","ruby","rubygem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amancevice.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-07-08T14:00:26.000Z","updated_at":"2023-11-13T21:06:57.000Z","dependencies_parsed_at":"2024-01-02T01:06:21.250Z","dependency_job_id":"e14243b7-4cf7-4f42-8e91-64d280abd7b5","html_url":"https://github.com/amancevice/rumrunner","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amancevice%2Frumrunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amancevice%2Frumrunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amancevice%2Frumrunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amancevice%2Frumrunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amancevice","download_url":"https://codeload.github.com/amancevice/rumrunner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243806070,"owners_count":20350775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","docker","dsl","multi-stage-dockerfiles","rake","ruby","rubygem"],"created_at":"2024-10-02T09:53:53.979Z","updated_at":"2025-03-16T08:32:07.030Z","avatar_url":"https://github.com/amancevice.png","language":"Ruby","readme":"[![Rum Runner](https://github.com/amancevice/rumrunner/blob/main/rum-runner.png?raw=true)](https://github.com/amancevice/rumrunner)\n![rubygems](https://img.shields.io/gem/v/rumrunner?logo=rubygems\u0026logoColor=eee\u0026style=flat-square)\n[![test](https://img.shields.io/github/actions/workflow/status/amancevice/rumrunner/test.yml?logo=github\u0026style=flat-square)](https://github.com/amancevice/rumrunner/actions/workflows/test.yml)\n[![coverage](https://img.shields.io/codeclimate/coverage/amancevice/rumrunner?logo=code-climate\u0026style=flat-square)](https://codeclimate.com/github/amancevice/rumrunner/test_coverage)\n[![maintainability](https://img.shields.io/codeclimate/maintainability/amancevice/rumrunner?logo=code-climate\u0026style=flat-square)](https://codeclimate.com/github/amancevice/rumrunner/maintainability)\n\n\u003csub\u003elogo by [seenamavaddat.com](http://seenamavaddat.com/)\u003c/sub\u003e\n\nRum Runner is a Rake-based utility for building multi-stage Dockerfiles.\n\nUsers can pair a multi-stage Dockerfile with a Rumfile that uses a Rake-like DSL to customize each stage's build options and dependencies.\n\nThe `rum` executable allows users to easily invoke builds, shell-into specific stages for debugging, and export artifacts from built containers.\n\nRum Runner has the following features:\n\n- Fully compatible with Rake\n- Rake-like DSL/CLI that enable simple annotation and execution of builds\n- Rumfiles are completely defined in standard Ruby syntax, like Rakefiles\n- Users can chain Docker build stages with prerequisites\n- Artifacts can be exported from stages\n- Shell tasks are automatically provided for every stage\n- Stage, artifact, and shell, steps can be customized\n\n**Origins**\n\nThis project was born from using Makefiles to drive multi-stage builds. For the most part this worked really well, but it became a bit of an ordeal to write for more complex projects. This tool is an attempt to recreate that general technique with minimal annotation and limited assumptions.\n\nView the docs on [rubydoc.info](https://www.rubydoc.info/github/amancevice/rumrunner)\n\n## Installation\n\n```bash\ngem install rumrunner\n```\n\n## Quickstart\n\nIf you have a multi-stage Dockerfile in your project and are unsure where to begin, use the `rum init` helper to create a template Rumfile for your project:\n\n```bash\ngem install rumrunner\nrum init \u003e Rumfile\nrum --tasks\n```\n\nThe `init` command will parse a Dockerfile in the current directory and output a simple Rumfile with each stage and its dependencies declared.\n\n## Example\n\nImagine a simple multi-stage Dockerfile:\n\n```Dockerfile\nFROM ruby AS build\n# Run build steps here...\n\nFROM ruby AS test\n# Run test steps here...\n\nFROM ruby AS deploy\n# Run deploy steps here...\n```\n\nCreate `Rumfile` and describe your build:\n\n```ruby\nrum :image_name do\n  tag \"1.2.3\"\n\n  stage :build\n  stage :test =\u003e :build\n  stage :deploy =\u003e :test\n\n  # rum build  =\u003e docker build --target build  --tag image_name:1.2.3-build .\n  # rum test   =\u003e docker build --target test   --tag image_name:1.2.3-test .\n  # rum deploy =\u003e docker build --target deploy --tag image_name:1.2.3-deploy .\nend\n```\n\nRun `rum --tasks` to view the installed tasks:\n\n```bash\nrum build                # Build `build` stage\nrum clean                # Remove any temporary images and products\nrum clean:build          # Remove any temporary images and products through `build` stage\nrum clean:deploy         # Remove any temporary images and products through `deploy` stage\nrum clean:test           # Remove any temporary images and products through `test` stage\nrum clobber              # Remove any generated files\nrum deploy               # Build `deploy` stage\nrum shell:build[shell]   # Shell into `build` stage\nrum shell:deploy[shell]  # Shell into `deploy` stage\nrum shell:test[shell]    # Shell into `test` stage\nrum test                 # Build `test` stage\n```\n\n## Customize Shells\n\nBy default, all stages have a `:shell` task that can be invoked to build and shell into a container for a stage. By default the container is run as an ephemeral container (`--rm`) in interactive with TTY allocated and a bash shell open.\n\nCustomize the shell for a stage with the `shell` method:\n\n```ruby\nrum :image_name do\n  stage :dev\n\n  shell :dev do\n    entrypoint \"/bin/zsh\"\n    rm         false\n    volume     \"#{Dir.pwd}:/var/task/\"\n  end\n\n  # rum dev =\u003e docker run --entrypoint /bin/zsh --volume $PWD:/var/task/ ...\nend\n```\n\n## Customize Stages\n\nStages can be customized with blocks:\n\n```ruby\nrum :image_name do\n  tag \"1.2.3\"\n\n  stage :build\n\n  stage :test =\u003e :build\n\n  stage :deploy =\u003e :test do\n    build_arg :AWS_ACCESS_KEY_ID\n    build_arg :AWS_SECRET_ACCESS_KEY\n    build_arg :AWS_DEFAULT_REGION =\u003e \"us-east-1\"\n    label     :Fizz\n  end\nend\n```\n\nMethods invoked inside the stage block are interpreted as options for the eventual `docker build` command.\n\n## Export Artifacts\n\nUse the `artifact` method to specify an artifact to be exported from the image.\n\n```ruby\nrum :image_name do\n  stage :build\n\n  artifact \"package.zip\" =\u003e :build\nend\n```\n\nBy default the container simply `cat`s the file from the container to the local file system, but more complex exports can be defined:\n\n```ruby\nrum :image_name do\n  stage :build\n\n  artifact \"package.zip\" =\u003e :build do\n    workdir \"/var/task/\"\n    cmd     %w[zip -r - .]\n  end\nend\n```\n\nMethods invoked inside the artifact block are interpreted as options for the eventual `docker run` command.\n\n## Default Task\n\nEvery `rum` declaration has a default task associated with it so that simply executing `rum` on the command line does something.\n\nIn the most simple case, the default task simply builds the image:\n\n```ruby\nrum :image_name\n# rum =\u003e docker build --tag image_name .\n```\n\nUse the `default` method inside the main block to set a default task or tasks:\n\n```ruby\nrum :image_name do\n  stage :build\n  stage :plan =\u003e :build\n\n  artifact \"package.zip\" =\u003e :build\n\n  default [\"package.zip\", :plan]\nend\n# rum =\u003e docker build --target build ...\n#        docker run ... \u003e package.zip\n#        docker build --target plan ...\n```\n\n## Shared ENV variables\n\nThe `env` method can be invoked in the `rum` block to declare a value that will be passed to all stages/artifacts/shells. For stages, the value will be passed using the `--build-arg` option; for artifacts and shells, the `--env` option.\n\n```ruby\nrum :image_name do\n  env :FIZZ =\u003e :BUZZ\n\n  stage :build\n\n  # rum build =\u003e docker build --build-arg FIZZ=BUZZ ...\nend\n```\n\n## Shells\n\nRun a stage task to build the image up to that stage and cache the image digest.\n\nRun with the `:shell` suffix to build the image and then shell into an instance of the image running as a temporary container.\n\nThe default shell is `/bin/sh`, but this can be overridden at runtime with the task arg, eg. `rum build:shell[/bin/bash]`\n\n## Build vs. Run\n\nAt the core, every directive within the `rum` block will eventually be interpreted as either a `docker build` or a `docker run` command. The type of directive is simply a way of specifying defaults for the command.\n\nIf you simply wish to define a named task that executes a build or a run, you can use the `build` or `run` directives:\n\n```ruby\nrum :image_name do\n  env :JAZZ =\u003e \"fuzz\"\n\n  build :fizz do\n    tag  \"image_name\"\n    path \".\"\n  end\n\n  run :buzz do\n    rm    true\n    image \"image_name\"\n    cmd   %w[echo hello]\n  end\n\n  # rum fizz =\u003e docker build --build-arg JAZZ=fuzz --tag image_name .\n  # rum buzz =\u003e docker run --rm --env JAZZ=fuzz image_name echo hello\nend\n```\n\nNote that the build/run commands will still import any shared ENV values defined above.\n\nIf this is undesirable, use the `clear_options` method inside your block to clear ALL the default options:\n\n```ruby\nrum :image_name do\n\n  env :JAZZ =\u003e \"fuzz\"\n\n  run :buzz do\n    clear_options\n    image \"image_name\"\n    cmd   %w[echo hello]\n  end\n\n  # rum buzz =\u003e docker run image_name echo hello\nend\n```\n\n## Blocks\n\nThe methods inside blocks for `build`, `run`, `stage`, `artifact`, and `shell` tasks are dynamically handled. Any option you might pass to the `docker run` or `docker build` command can be used.\n\nSimply drop any leading `-`s from the option and convert to snake-case.\n\nEg,\n\n`--build-arg` becomes `build_arg`\n\n`--env-file` becomes `env_file`.\n\n## Task Naming Convention\n\nAs of v0.3, rum runner uses a \"verb-first\" naming convention (eg. `clean:stage`) for tasks.\n\nTo revert to the previous convention of \"stage-first\" (eg. `stage:clean`) use the environmental variable `RUM_TASK_NAMES`:\n\n```bash\nexport RUM_TASK_NAMES=STAGE_FIRST  # =\u003e rum stage:clean\nexport RUM_TASK_NAMES=VERB_FIRST   # =\u003e rum clean:stage (default)\n```\n\n## Image Naming Convention\n\nThe name of the images are taken from the first argument to the main block and appended with the name of the stage.\n\nIn the above example, built images would build be named:\n\n- `image_name:1.2.3-build`\n- `image_name:1.2.3-test`\n- `image_name:1.2.3-deploy`\n\nThe first argument to the main block can be any Docker image reference:\n\n```ruby\nrum :\"registry:5000/username/image\" do\n  #...\nend\n```\n\n## Dockerfile Location\n\nImages built use the current working directory as the default path to the Dockerfile, but this can be modified:\n\n```ruby\nrum :image_name =\u003e \"some/dockerfile/dir\" do\n  # ...\nend\n```\n\nThe default Dockerfile path can also be set using the `RUM_PATH` environmental variable.\n\n## Docker Image Digest Location\n\nImages build with the `stage` task have their digests cached for easy lookup.\n\nThe default location for the digests is in `.docker`, but that can be modified:\n\n```ruby\nrum :image_name =\u003e [\".\", \"tmp\"] do\n  # ...\nend\n```\n\nNote that in this case you must also explicitly define the Dockerfile path.\n\nThe default digest path can also be set using the `RUM_HOME` environmental variable.\n\n## Integrate with Rake\n\nIt isn't strictly necessary to include a `Rumfile` in your project. Rum Runner can be included in any `Rakefile` and run with the `rake` command:\n\n```ruby\n# ./Rakefile\n\nrequire \"rumrunner\"\n\nnamespace :rum do\n  rum :image_name do\n    stage :build\n    stage :test =\u003e :build\n  end\nend\n```\n\n```bash\n$ rake --tasks\n\nrake rum:build # ...\nrake rum:test  # ...\n```\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famancevice%2Frumrunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famancevice%2Frumrunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famancevice%2Frumrunner/lists"}