{"id":13558284,"url":"https://github.com/discourse/pups","last_synced_at":"2025-12-17T09:05:28.894Z","repository":{"id":49468415,"uuid":"13978964","full_name":"discourse/pups","owner":"discourse","description":"Simple yaml based bootstrapper for Linux machines","archived":false,"fork":false,"pushed_at":"2025-07-08T06:42:22.000Z","size":96,"stargazers_count":159,"open_issues_count":2,"forks_count":22,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-07-08T07:45:31.054Z","etag":null,"topics":["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/discourse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE.txt","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,"publiccode":null,"codemeta":null}},"created_at":"2013-10-30T06:21:52.000Z","updated_at":"2024-12-01T23:21:33.000Z","dependencies_parsed_at":"2024-11-04T09:30:46.197Z","dependency_job_id":"81424ee3-900a-4682-bbc7-2861f75946e7","html_url":"https://github.com/discourse/pups","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/discourse/pups","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fpups","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fpups/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fpups/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fpups/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/discourse","download_url":"https://codeload.github.com/discourse/pups/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fpups/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27780896,"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","status":"online","status_checked_at":"2025-12-17T02:00:08.291Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["rubygem"],"created_at":"2024-08-01T12:04:51.652Z","updated_at":"2025-12-17T09:05:28.885Z","avatar_url":"https://github.com/discourse.png","language":"Ruby","readme":"# pups\n\nSimple YAML--based bootstrapper\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'pups'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install pups\n\n## Usage\n\npups is a small library that allows you to automate the process of creating Unix images.\n\n```\nUsage: pups [options] [FILE|--stdin]\n        --stdin                      Read input from stdin.\n        --quiet                      Don't print any logs.\n        --ignore \u003celements\u003e          Ignore specific configuration elements, multiple elements can be provided (comma-delimited).\n                                     Useful if you want to skip over config in a pups execution.\n                                     e.g. `--ignore env,params`.\n        --tags \u003celements\u003e            Only run tagged commands.\n        --skip-tags \u003celements\u003e       Run all but listed tagged commands.\n        --gen-docker-run-args        Output arguments from the pups configuration for input into a docker run command. All other pups config is ignored.\n    -h, --help\n```\n\npups requires input either via a stdin stream or a filename. The entire input is parsed prior to any templating or command execution.\n\nExample:\n\n```\n# somefile.yaml\nparams:\n  hello: hello world\n\nrun:\n  - exec: /bin/bash -c 'echo $hello \u003e\u003e hello'\n```\n\nRunning: `pups somefile.yaml` will execute the shell script resulting in a file called \"hello\" with the contents \"hello world\".\n\n### Features\n\n#### Filtering run commands by tags\n\nThe `--tags` and `--skip-tags` argument allows pups to target a subset of commands listed in the somefile.yaml. To use this, you may tag your commands in the runblock. `--tags` will only run commands when commands have a matching tag. `--skip-tags` will skip when commands have a matching tag.\n\nNote, hooks from tagged commands will be present or absent depending on if the tag is filtered out or not as well. A command filtered out by targeting tag will also filter out the command's `before_` and `after_` hooks.\n\nExample:\n\n```\n# somefile.yaml\n\nrun:\n  - exec:\n      cmd: /bin/bash -c 'echo hello \u003e\u003e hello'\n      tag: sometag\n  - exec:\n      cmd: /bin/bash -c 'echo hi \u003e\u003e hello'\n      tag: anothertag\n  - exec:\n      cmd: /bin/bash -c 'echo goodbye \u003e\u003e hello'\n      tag: thirdtag\n```\nRunning: `pups --tags=\"sometag,anothertag\" somefile.yaml` will not run the echo goodbye statement.\n\nRunning: `pups --skip-tags=\"sometag,anothertag\" somefile.yaml` will ONLY run the echo goodbye statement.\n\n#### Parameter overriding\n\nThe `--params` argument allows pups to dynamically override params set within a configuration for the single pups run.\n\nNote, it is expected to be of the form `key=value`. If it is malformed, a warning will be thrown.\n\nExample:\n\n```\n# somefile.yaml\n\nparams:\n  param1: false_prophet\n  param2: also overridden\nrun:\n  - exec:\n      cmd: /bin/bash -c 'echo $param1 $param2 \u003e\u003e hello'\n```\nRunning `pups --params=\"param1=true_value,param2=other_true_value\" somefile.yaml` will overwrite param1 and param2 with true_value and other_true_value respectively\n\n#### Docker run argument generation\n\nThe `--gen-docker-run-args` argument is used to make pups output arguments be in the format of `docker run \u003carguments output\u003e`. Specifically, pups\nwill take any `env`, `volume`, `labels`, `links`, and `expose` configuration, and coerce that into the format expected by `docker run`. This can be useful\nwhen pups is being used to configure an image (e.g. by executing a series of commands) that is then going to be run as a container. That way, the runtime and image\nconfiguration can be specified within the same yaml files.\n\n\n#### Environment Variables\n\nBy default, pups automatically imports your environment variables and includes them as params.\n\n```\n# In bash\nexport SECRET_KEY=\"secret value\"\n\n# In somefile.yaml\nrun:\n  - exec: echo \"$SECRET_KEY\"\n```\n\nRunning the above code with pups will produce `secret value`.\n\n#### Execution\n\nRun multiple commands in one path:\n\n```\nrun:\n  - exec:\n      cd: some/path\n      cmd:\n        - echo 1\n        - echo 2\n```\n\nRun commands in the background (for services etc)\n\n```\nrun:\n  - exec:\n      cmd: /usr/bin/sshd\n      background: true\n```\n\nSuppress exceptions on certain commands\n\n```\nrun:\n  - exec:\n      cmd: /test\n      raise_on_fail: false\n```\n\n#### Replacements:\n\n```\nrun:\n  - replace:\n      filename: \"/etc/redis/redis.conf\"\n      from: /^pidfile.*$/\n      to: \"\"\n```\n\nWill substitute the regex with blank, removing the pidfile line\n\n```\nrun:\n  - replace:\n      filename: \"/etc/nginx/conf.d/discourse.conf\"\n      from: /upstream[^\\}]+\\}/m\n      to: \"upstream discourse {\n        server 127.0.0.1:3000;\n      }\"\n```\n\nAdditional params:\n\nGlobal replace (as opposed to first match)\n```\nglobal: true\n```\n\n#### Hooks\n\nExecute commands before and after a specific command by defining a hook.\n\n```\nrun\n  - exec:\n      hook: hello\n      cmd: echo 'Hello'\n\nhooks:\n  before_hello:\n    - exec:\n        cmd: echo 'Starting...'\n\n  after_hello:\n    - exec:\n        cmd: echo 'World'\n```\n\n#### Merge yaml files\n\n```\nhome: /var/www/my_app\nparams:\n  database_yml:\n    production:\n      username: discourse\n      password: foo\n\nrun:\n  - merge: $home/config/database.yml $database_yml\n\n```\n\nWill merge the yaml file with the inline contents.\n\n#### A common environment\n\nEnvironment variables can be specified under the `env` key, which will be included in the environment for the template.\n\n```\nenv:\n  MY_ENV: \"a couple of words\"\nrun:\n  - exec: echo $MY_ENV \u003e tmpfile\n```\n\n`tmpfile` will contain `a couple of words`.\n\nYou can also specify variables to be templated within the environment, such as:\n\n```\nenv:\n  greeting: \"hello, {{location}}!\"\nenv_template:\n  location: world\n```\n\nIn this example, the `greeting` environment variable will be set to `hello, world!` during initialisation as the `{{location}}` variable will be templated as `world`.\nPups will also look in the environment itself at runtime for template variables, prefixed with `env_template_\u003cvariable name\u003e`.\nNote that strings should be quoted to prevent YAML from parsing the `{ }` characters.\n\nAll commands executed will inherit the environment once parsing and variable interpolation has been completed.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n","funding_links":[],"categories":["Ruby","others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscourse%2Fpups","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiscourse%2Fpups","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscourse%2Fpups/lists"}