{"id":18492707,"url":"https://github.com/voxpupuli/librarian-puppet","last_synced_at":"2025-04-08T21:31:22.889Z","repository":{"id":5773022,"uuid":"48424664","full_name":"voxpupuli/librarian-puppet","owner":"voxpupuli","description":null,"archived":false,"fork":true,"pushed_at":"2023-09-04T14:06:22.000Z","size":886,"stargazers_count":95,"open_issues_count":31,"forks_count":38,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-10-29T14:22:32.117Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"rodjek/librarian-puppet","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voxpupuli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-12-22T10:03:33.000Z","updated_at":"2024-05-09T08:50:57.000Z","dependencies_parsed_at":"2023-09-24T10:28:14.487Z","dependency_job_id":null,"html_url":"https://github.com/voxpupuli/librarian-puppet","commit_stats":{"total_commits":437,"total_committers":64,"mean_commits":6.828125,"dds":0.6086956521739131,"last_synced_commit":"dc8e1aba42201d2590e8101e6c01648856c445a3"},"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Flibrarian-puppet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Flibrarian-puppet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Flibrarian-puppet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Flibrarian-puppet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voxpupuli","download_url":"https://codeload.github.com/voxpupuli/librarian-puppet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247386257,"owners_count":20930618,"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":["hacktoberfest"],"created_at":"2024-11-06T13:10:23.730Z","updated_at":"2025-04-08T21:31:22.860Z","avatar_url":"https://github.com/voxpupuli.png","language":"Ruby","funding_links":[],"categories":["Modules"],"sub_categories":["Modules Management"],"readme":"# Librarian-puppet\n\n[![License](https://img.shields.io/github/license/voxpupuli/librarian-puppet.svg)](https://github.com/voxpupuli/librarian-puppet/blob/master/LICENSE)\n[![Test](https://github.com/voxpupuli/librarian-puppet/actions/workflows/test.yml/badge.svg)](https://github.com/voxpupuli/librarian-puppet/actions/workflows/test.yml)\n[![Release](https://github.com/voxpupuli/librarian-puppet/actions/workflows/release.yml/badge.svg)](https://github.com/voxpupuli/librarian-puppet/actions/workflows/release.yml)\n[![RubyGem Version](https://img.shields.io/gem/v/librarian-puppet.svg)](https://rubygems.org/gems/librarian-puppet)\n[![RubyGem Downloads](https://img.shields.io/gem/dt/librarian-puppet.svg)](https://rubygems.org/gems/librarian-puppet)\n[![Donated by Tim Sharpe](https://img.shields.io/badge/donated%20by-Tim%20Sharpe-fb7047.svg)](#transfer-notice)\n\n## Introduction\n\nLibrarian-puppet is a bundler for your puppet infrastructure.  You can use\nlibrarian-puppet to manage the puppet modules your infrastructure depends on,\nwhether the modules come from the [Puppet Forge](https://forge.puppet.com/),\nGit repositories or just a path.\n\n* Librarian-puppet can reuse the dependencies listed in your `Modulefile` or `metadata.json`\n* Forge modules can be installed from [Puppetlabs Forge](https://forge.puppet.com/) or an internal Forge such as [Pulp](http://www.pulpproject.org/)\n* Git modules can be installed from a branch, tag or specific commit, optionally using a path inside the repository\n* Modules can be installed from GitHub using tarballs, without needing Git installed\n* Modules can be installed from a filesystem path\n* Module dependencies are resolved transitively without needing to list all the modules explicitly\n\n\nLibrarian-puppet manages your `modules/` directory for you based on your\n`Puppetfile`.  Your `Puppetfile` becomes the authoritative source for what\nmodules you require and at what version, tag or branch.\n\nOnce using Librarian-puppet you should not modify the contents of your `modules`\ndirectory.  The individual modules' repos should be updated, tagged with a new\nrelease and the version bumped in your Puppetfile.\n\nIt is based on [Librarian](https://github.com/applicationsonline/librarian), a\nframework for writing bundlers, which are tools that resolve, fetch, install,\nand isolate a project's dependencies.\n\n## Versions\n\nLibrarian-Puppet 5.0.0 and newer requires Ruby \u003e= 2.7 and Puppet \u003e= 6. Use version 4.0.1 if you need support for Puppet 6 or Ruby 2.6 or earlier.\n\nLibrarian-Puppet 4.0.0 and newer requires Ruby \u003e= 2.5 and Puppet \u003e= 5. Use version 3.0.1 is you need support for Puppet 3 or Puppet 4, or Ruby 2.4 or earlier.\n\nLibrarian-Puppet 3.0.0 and newer requires Ruby \u003e= 2.0. Use version 2.2.4 if you need support for Puppet 3.7 or earlier, or Ruby 1.9 or earlier. Note that [Puppet 4.10 and newer require Ruby 2.1](https://puppet.com/docs/puppet/4.10/system_requirements.html#prerequisites) or newer.\n\nLibrarian-Puppet 2.0.0 and newer requires Ruby \u003e= 1.9 and uses Puppet Forge API v3. For Ruby 1.8 use 1.5.0.\n\nSee the [Changelog](CHANGELOG.md) for more details.\n\n## The Puppetfile\n\nEvery Puppet repository that uses Librarian-puppet may have a file named\n`Puppetfile`, `metadata.json` or `Modulefile` in the root directory of that repository.\nThe full specification\nfor which modules your puppet infrastructure repository depends goes in here.\n\n### Simple usage\n\nIf no Puppetfile is present, `librarian-puppet` will download all the dependencies\nlisted in your `metadata.json` or `Modulefile` from the Puppet Forge,\nas if the Puppetfile contained\n\n    forge \"https://forgeapi.puppet.com\"\n\n    metadata\n\n\n### Example Puppetfile\n\n    forge \"https://forgeapi.puppet.com\"\n\n    mod 'puppetlabs-razor'\n    mod 'puppetlabs-ntp', \"0.0.3\"\n\n    mod 'puppetlabs-apt',\n      :git =\u003e \"git://github.com/puppetlabs/puppetlabs-apt.git\"\n\n    mod 'puppetlabs-stdlib',\n      :git =\u003e \"git://github.com/puppetlabs/puppetlabs-stdlib.git\"\n\n    mod 'puppetlabs-apache', '0.6.0',\n      :github_tarball =\u003e 'puppetlabs/puppetlabs-apache'\n\n    mod 'acme-mymodule', :path =\u003e './some_folder'\n\n    exclusion 'acme-bad_module'\n\n\n### Recursive module dependency resolution\n\nWhen fetching a module all dependencies specified in its\n`Modulefile`, `metadata.json` and `Puppetfile` will be resolved and installed.\n\n### Puppetfile Breakdown\n\n    forge \"https://forgeapi.puppet.com\"\n\nThis declares that we want to use the official Puppet Labs Forge as our default\nsource when pulling down modules.  If you run your own local forge, you may\nwant to change this.\n\n    metadata\n\nDownload all the dependencies listed in your `metadata.json` or `Modulefile` from the Puppet Forge.\n\n    mod 'puppetlabs-razor'\n\nPull in the latest version of the Puppet Labs Razor module from the default\nsource.\n\n    mod 'puppetlabs-ntp', \"0.0.3\"\n\nPull in version 0.0.3 of the Puppet Labs NTP module from the default source.\n\n    mod 'puppetlabs-apt',\n      :git =\u003e \"git://github.com/puppetlabs/puppetlabs-apt.git\"\n\nOur puppet infrastructure repository depends on the `apt` module from the\nPuppet Labs GitHub repos and checks out the `master` branch.\n\n    mod 'puppetlabs-apt',\n      :git =\u003e \"git://github.com/puppetlabs/puppetlabs-apt.git\",\n      :ref =\u003e '0.0.3'\n\nOur puppet infrastructure repository depends on the `apt` module from the\nPuppet Labs GitHub repos and checks out a tag of `0.0.3`.\n\n    mod 'puppetlabs-apt',\n      :git =\u003e \"git://github.com/puppetlabs/puppetlabs-apt.git\",\n      :ref =\u003e 'feature/master/dans_refactor'\n\nOur puppet infrastructure repository depends on the `apt` module from the\nPuppet Labs GitHub repos and checks out the `dans_refactor` branch.\n\nWhen using a Git source, we do not have to use a `:ref =\u003e`.\nIf we do not, then librarian-puppet will assume we meant the `master` branch.\n\nIf we use a `:ref =\u003e`, we can use anything that Git will recognize as a ref.\nThis includes any branch name, tag name, SHA, or SHA unique prefix. If we use a\nbranch, we can later ask Librarian-puppet to update the module by fetching the\nmost recent version of the module from that same branch.\n\nNote that Librarian-puppet recognizes the [r10k Puppetfile's](https://github.com/puppetlabs/r10k/blob/master/doc/puppetfile.mkd) additional\noptions, `:tag`, `:commit`, and `:branch`, but only as aliases for `:ref`.\nThat is, there is no implementation of r10k's optimizations around fetching\nthese different types of git objects.\n\nThe Git source also supports a `:path =\u003e` option. If we use the path option,\nLibrarian-puppet will navigate down into the Git repository and only use the\nspecified subdirectory. Some people have the habit of having a single repository\nwith many modules in it. If we need a module from such a repository, we can\nuse the `:path =\u003e` option here to help Librarian-puppet drill down and find the\nmodule subdirectory.\n\n    mod 'puppetlabs-apt',\n      :git =\u003e \"git://github.com/fake/puppet-modules.git\",\n      :path =\u003e \"modules/apt\"\n\nOur puppet infrastructure repository depends on the `apt` module, which we have\nstored as a directory under our `puppet-modules` git repos.\n\n    mod 'puppetlabs-apache', '0.6.0',\n      :github_tarball =\u003e 'puppetlabs/puppetlabs-apache'\n\nOur puppet infrastructure repository depends on the `puppetlabs-apache` module,\nto be downloaded from GitHub tarball.\n\n    mod 'acme-mymodule', :path =\u003e './some_folder'\n\nOur puppet infrastructure repository depends on the `acme-mymodule` module,\nwhich is already in the filesystem.\n\n    exclusion 'acme-bad_module'\n\nExclude the module `acme-bad_module` from resolution and installation.\n\n## How to Use\n\nInstall librarian-puppet:\n\n    $ gem install librarian-puppet\n\nPrepare your puppet infrastructure repository:\n\n    $ cd ~/path/to/puppet-inf-repos\n    $ (git) rm -rf modules\n    $ librarian-puppet init\n\nLibrarian-puppet takes over your `modules/` directory, and will always\nreinstall (if missing) the modules listed the `Puppetfile.lock` into your\n`modules/` directory, therefore you do not need your `modules/` directory to be\ntracked in Git.\n\nLibrarian-puppet uses a `.tmp/` directory for tempfiles and caches. You should\nnot track this directory in Git.\n\nRunning `librarian-puppet init` will create a skeleton Puppetfile for you as\nwell as adding `tmp/` and `modules/` to your `.gitignore`.\n\n    $ librarian-puppet install [--clean] [--verbose]\n\nThis command looks at each `mod` declaration and fetches the module from the\nsource specified.  This command writes the complete resolution into\n`Puppetfile.lock` and then copies all of the fetched modules into your\n`modules/` directory, overwriting whatever was there before.\n\nLibrarian-puppet support both v1 and v3 of the Puppet Forge API.\nSpecify a specific API version when installing modules:\n\n    $ librarian-puppet install --use-v1-api # use the v1 API\n    $ librarian-puppet install --no-use-v1-api # use the v3 API; this is the default\n\nGet an overview of your `Puppetfile.lock` with:\n\n    $ librarian-puppet show\n\nInspect the details of specific resolved dependencies with:\n\n    $ librarian-puppet show NAME1 [NAME2, ...]\n\nFind out which dependencies are outdated and may be updated:\n\n    $ librarian-puppet outdated [--verbose]\n\nUpdate the version of a dependency:\n\n    $ librarian-puppet update apt [--verbose]\n    $ git diff Puppetfile.lock\n    $ git add Puppetfile.lock\n    $ git commit -m \"bumped the version of apt up to 0.0.4.\"\n\n## Configuration\n\nConfiguration comes from three sources with the following highest-to-lowest\nprecedence:\n\n* The local config (`./.librarian/puppet/config`)\n* The environment\n* The global config (`~/.librarian/puppet/config`)\n\nYou can inspect the final configuration with:\n\n    $ librarian-puppet config\n\nYou can find out where a particular key is set with:\n\n    $ librarian-puppet config KEY\n\nYou can set a key at the global level with:\n\n    $ librarian-puppet config KEY VALUE --global\n\nAnd remove it with:\n\n    $ librarian-puppet config KEY --global --delete\n\nYou can set a key at the local level with:\n\n    $ librarian-puppet config KEY VALUE --local\n\nAnd remove it with:\n\n    $ librarian-puppet config KEY --local --delete\n\nYou cannot set or delete environment-level config keys with the CLI.\n\nConfiguration set at either the global or local level will affect subsequent\ninvocations of `librarian-puppet`. Configurations set at the environment level are\nnot saved and will not affect subsequent invocations of `librarian-puppet`.\n\nYou can pass a config at the environment level by taking the original config key\nand transforming it: replace hyphens (`-`) with underscores (`_`) and periods\n(`.`) with doubled underscores (`__`), uppercase, and finally prefix with\n`LIBRARIAN_PUPPET_`. For example, to pass a config in the environment for the key\n`part-one.part-two`, set the environment variable\n`LIBRARIAN_PUPPET_PART_ONE__PART_TWO`.\n\nConfiguration affects how various commands operate.\n\n* The `path` config sets the directory to install to. If a relative\n  path, it is relative to the directory containing the `Puppetfile`. The\n  equivalent environment variable is `LIBRARIAN_PUPPET_PATH`.\n\n* The `tmp` config sets the cache directory for librarian. If a relative\n  path, it is relative to the directory containing the `Puppetfile`. The\n  equivalent environment variable is `LIBRARIAN_PUPPET_TMP`.\n\nConfiguration can be set by passing specific options to other commands.\n\n* The `path` config can be set at the local level by passing the `--path` option\n  to the `install` command. It can be unset at the local level by passing the\n  `--no-path` option to the `install` command. Note that if this is set at the\n  environment or global level then, even if `--no-path` is given as an option,\n  the environment or global config will be used.\n\n\n## Rsync Option\n\nThe default convergence strategy between the cache and the module directory is\nto execute an `rm -r` on the module directory and just `cp -r` from the cache.\nThis causes the module to be removed from the module path every time librarian\npuppet updates, regardless of whether the content has changed. This can cause\nsome problems in environments with lots of change. The problem arises when the\nmodule directory gets removed while Puppet is trying to read files inside it.\nThe `puppet master` process will lose its CWD and the catalog will fail to\ncompile. To avoid this, you can use `rsync` to implement a more conservative\nconvergence strategy. This will use `rsync` with the `-avz` and `--delete`\nflags instead of a `rm -r` and `cp -r`. To use this feature, just set the\n`rsync` configuration setting to `true`.\n\n    $ librarian-puppet config rsync true --global\n\nAlternatively, using an environment variable:\n\n    LIBRARIAN_PUPPET_RSYNC='true'\n\nNote that the directories will still be purged if you run librarian-puppet with\nthe --clean or --destructive flags.\n\n## How to Contribute\n\n * Pull requests please.\n * Bonus points for feature branches.\n\n## Reporting Issues\n\nBug reports to the github issue tracker please.\nPlease include:\n\n * Relevant `Puppetfile` and `Puppetfile.lock` files\n * Version of ruby, librarian-puppet, and puppet\n * What distro\n * Please run the `librarian-puppet` commands in verbose mode by using the\n  `--verbose` flag, and include the verbose output in the bug report as well.\n\n\n## Transfer Notice\n\nThis plugin was originally authored by [Tim Sharpe](https://github.com/rodjek).\nThe maintainer preferred that [Vox Pupuli](https://voxpupuli.org/) take ownership of the module for future improvement and maintenance.\nExisting pull requests and issues were transferred, please fork and continue to contribute [here](https://github.com/voxpupuli/librarian-puppet).\n\n## License\nPlease see the [LICENSE](https://github.com/voxpupuli/librarian-puppet/blob/master/LICENSE)\nfile.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Flibrarian-puppet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoxpupuli%2Flibrarian-puppet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Flibrarian-puppet/lists"}