{"id":13617515,"url":"https://github.com/chef/omnibus","last_synced_at":"2025-05-14T09:06:48.013Z","repository":{"id":2471424,"uuid":"3444030","full_name":"chef/omnibus","owner":"chef","description":"Easily create full-stack installers for your project across a variety of platforms.","archived":false,"fork":false,"pushed_at":"2025-04-24T13:20:02.000Z","size":36857,"stargazers_count":1292,"open_issues_count":65,"forks_count":300,"subscribers_count":92,"default_branch":"main","last_synced_at":"2025-05-14T09:05:55.690Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chef.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-02-14T21:15:35.000Z","updated_at":"2025-04-04T02:13:35.000Z","dependencies_parsed_at":"2023-10-04T14:30:45.867Z","dependency_job_id":"a6c68fd5-124b-4691-872c-a87d81081841","html_url":"https://github.com/chef/omnibus","commit_stats":{"total_commits":2410,"total_committers":176,"mean_commits":"13.693181818181818","dds":0.7,"last_synced_commit":"a1ed55c2e0fdeb06b3c3f3041fe4d0c563233ba4"},"previous_names":["opscode/omnibus","opscode/omnibus-ruby"],"tags_count":216,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fomnibus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fomnibus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fomnibus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fomnibus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chef","download_url":"https://codeload.github.com/chef/omnibus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254110374,"owners_count":22016391,"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":[],"created_at":"2024-08-01T20:01:42.996Z","updated_at":"2025-05-14T09:06:47.992Z","avatar_url":"https://github.com/chef.png","language":"Ruby","funding_links":[],"categories":["Ruby","Software","Ruby Binary Packagers"],"sub_categories":["Packaging"],"readme":"# ![Omnibus Icon](lib/omnibus/assets/README-logo.png) Omnibus\n\n[![Gem Version](http://img.shields.io/gem/v/omnibus.svg)][gem]\n[![Build Status](https://badge.buildkite.com/446fd6049a9a5eeab50112aba117d3b7670ec085acb91f78dd.svg?branch=master)](https://buildkite.com/chef-oss/chef-omnibus-master-verify)\n\n**Umbrella Project**: [Chef Foundation](https://github.com/chef/chef-oss-practices/blob/master/projects/chef-foundation.md)\n\n**Project State**: [Active](https://github.com/chef/chef-oss-practices/blob/master/repo-management/repo-states.md#active)\n\n**Issues [Response Time Maximum](https://github.com/chef/chef-oss-practices/blob/master/repo-management/repo-states.md)**: 14 days\n\n**Pull Request [Response Time Maximum](https://github.com/chef/chef-oss-practices/blob/master/repo-management/repo-states.md)**: 14 days\n\nEasily create full-stack installers for your project across a variety of platforms.\n\nSeth Chisamore and Christopher Maier of CHEF gave an introductory talk on Omnibus at ChefConf 2013, entitled **Eat the Whole Bowl: Building a Full-Stack Installer with Omnibus**:\n\n- [Slides](https://speakerdeck.com/schisamo/eat-the-whole-bowl-building-a-full-stack-installer-with-omnibus)\n\nThis project is managed by the CHEF Release Engineering team. For more information on the Release Engineering team's contribution, triage, and release process, please consult the [CHEF Release Engineering OSS Management Guide](https://docs.google.com/a/opscode.com/document/d/1oJB0vZb_3bl7_ZU2YMDBkMFdL-EWplW1BJv_FXTUOzg/edit).\n\n## Prerequisites\n\nOmnibus is designed to run with a minimal set of prerequisites. You will need the following:\n\n- Ruby 2.6+\n\n## Get Started\n\nOmnibus provides both a DSL for defining Omnibus projects for your software, as well as a command-line tool for generating installer artifacts from that definition.\n\nTo get started, install Omnibus locally on your workstation.\n\n```bash\n$ gem install omnibus\n```\n\nYou can now create an Omnibus project in your current directory by using the project generator feature.\n\n```bash\n$ omnibus new $MY_PROJECT_NAME\n```\n\nThis will generate a complete project skeleton in the directory `omnibus-$MY_PROJECT_NAME`\n\nBy default this will make a directory called `omnibus-$MY_PROJECT_NAME` assuming you're keeping your omnibus config separate from the repo. However, keeping it *in* your repo is a common practice, so feel to rename this directory to `omnibus` and place it in the top level of your projects source repo.\n\n```bash\n$ cd omnibus-$MY_PROJECT_NAME\n$ bundle install --binstubs\n```\n\nMore details can be found in the generated project's README file.\n\nOmnibus determines the platform for which to build an installer based on **the platform it is currently running on**. That is, you can only generate a `.deb` file on a Debian-based system. To alleviate this caveat, the generated project includes a [Test Kitchen](http://kitchen.ci) setup suitable for generating a series of Omnibus projects.\n\n## More documentation\n\n- [Building on Debian](docs/Building%20on%20Debian.md)\n- [Building on OSX](docs/Building%20on%20OSX.md)\n- [Building on RHEL](docs/Building%20on%20RHEL.md)\n- [Building on Windows](docs/Building%20on%20Windows.md)\n- [Build Cache](docs/Build%20Cache.md)\n\n## Configuration DSL\n\nThough the template project will build, it will not do anything exciting. For that, you need to use the Omnibus DSL to define the specifics of your application.\n\n### Config\n\nIf present, Omnibus will use a top-level configuration file named `omnibus.rb` at the root of your repository. This file is loaded at runtime and includes a number of configuration tunables. Here is an example:\n\n```ruby\n# Build locally (instead of /var)\n# -------------------------------\nbase_dir './local'\n\n# Disable git caching\n# ------------------------------\nuse_git_caching false\n\n# Enable S3 asset caching\n# ------------------------------\nuse_s3_caching true\ns3_bucket      ENV['S3_BUCKET']\n\n# There are three ways to authenticate to the S3 bucket\n\n# 1. set `s3_access_key` and `s3_secret_key`\ns3_access_key  ENV['S3_ACCESS_KEY']\ns3_secret_key  ENV['S3_SECRET_KEY']\n\n# 2. set `s3_profile` to use an AWS profile in the Shared Credentials files\n#s3_profile    ENV['S3_PROFILE']\n\n# 3. set `s3_iam_role_arn` to use an AWS IAM role\n#s3_iam_role_arn    ENV['S3_IAM_ROLE_ARN']\n```\n\nFor more information, please see the [`Config` documentation](http://www.rubydoc.info/github/chef/omnibus/Omnibus/Config).\n\nYou can tell Omnibus to load a different configuration file by passing the `--config` option to any command:\n\n```shell\n$ bin/omnibus --config /path/to/config.rb\n```\n\nFinally, you can override a specific configuration option at the command line using the `--override` flag. This takes ultimate precedence over any configuration file values:\n\n```shell\n$ bin/omnibus --override use_git_caching:false\n```\n\n### Projects\n\nA Project DSL file defines your actual application; this is the thing you are creating a full-stack installer for in the first place. It provides a means to define the dependencies of the project (again, as specified in Software DSL definition files), as well as ways to set installer package metadata.\n\nAll project definitions must be in the `config/projects` directory of your Omnibus repository.\n\n```ruby\nname            \"chef-full\"\nmaintainer      \"YOUR NAME\"\nhomepage        \"http://yoursite.com\"\n\ninstall_dir     \"/opt/chef\"\nbuild_version   \"0.10.8\"\nbuild_iteration 4\n\ndependency \"chef\"\n```\n\nSome DSL methods available include:\n\nDSL Method        | Description\n:---------------- | ----------------------------------------------------------------\n`name`            | The name of the project\n`install_dir`     | The desired install location of the package\n`build_version`   | The package version\n`build_iteration` | The package iteration number\n`dependency`      | An Omnibus software-defined component to include in this package\n`package`         | Invoke a packager-specific DSL\n`compress`        | Invoke a compressor-specific DSL\n\nBy default a timestamp is appended to the build_version. You can turn this behavior off by setting `append_timestamp` to `false` in your `omnibus.rb` or using `--override append_timestamp:false` at the command line.\n\nFor more information, please see the [`Project` documentation](http://www.rubydoc.info/github/chef/omnibus/Omnibus/Project).\n\n### Software\n\nOmnibus \"software\" files define individual software components that go into making your overall package. They are the building blocks of your application. The Software DSL provides a way to define where to retrieve the software sources, how to build them, and what dependencies they have. These dependencies are also defined in their own Software DSL files, thus forming the basis for a dependency-aware build ordering.\n\nAll Software definitions should go in the `config/software` directory of your Omnibus project repository.\n\nHere is an example:\n\n```ruby\nname \"ruby\"\ndefault_version \"1.9.2-p290\"\nsource url: \"http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-#{version}.tar.gz\",\n       md5: \"604da71839a6ae02b5b5b5e1b792d5eb\"\n\ndependency \"zlib\"\ndependency \"ncurses\"\ndependency \"openssl\"\n\nrelative_path \"ruby-#{version}\"\n\nbuild do\n  command \"./configure\"\n  command \"make\"\n  command \"make install\"\nend\n```\n\nSome of the DSL methods available include:\n\nDSL Method        | Description\n:---------------- | -------------------------------------------------------------------\n`name`            | The name of the software component (this should come first)\n`default_version` | The version of the software component\n`source`          | Directions to the location of the source\n`dependency`      | An Omnibus software-defined component that this software depends on\n`relative_path`   | The relative path of the extracted tarball\n`build`           | The build instructions\n\nFor more DSL methods, please consult the [`Software` documentation](http://rubydoc.info/github/chef/omnibus/Omnibus/Software).\n\nAdditionally, there are a number of DSL methods available inside the `build` block:\n\nDSL Method          | Description\n:------------------ | -------------------------------------------------------------\n`command`           | Execute a single shell command\n`make`              | Run make (with or without args), using gmake when appropriate\n`patch`             | Apply a patch from disk\n`workers`           | The maximum number of builders\n`windows_safe_path` | Format the path to be safe for shelling out on Windows\n`go`                | Execute the code as the embedded Go\n`ruby`              | Execute the code as the embedded Ruby\n`gem`               | Execute the code as the embedded Rubygems\n`bundle`            | Execute the code as the embedded Bundler\n`rake`              | Execute the code as the embedded Rake gem\n`block`             | Execute Ruby block at build time\n`erb`               | Render the given ERB template\n`mkdir`             | Create the given directory\n`touch`             | Create the given empty file\n`delete`            | Remove the given file or directory\n`strip`             | Strip symbols from binaries on a given file or directory\n`copy`              | Copy a to b\n`move`              | Move a to b\n`link`              | Link a to b\n`sync`              | Copy all files from a to b, removing any union files\n\nFor more DSL methods, please consult the [`Builder` documentation](http://rubydoc.info/github/chef/omnibus/Omnibus/Builder).\n\nYou can support building multiple versions of the same software in the same software definition file using the `version` method and giving a block:\n\n```ruby\nname \"ruby\"\ndefault_version \"1.9.2-p290\"\n\nversion \"1.9.2-p290\" do\n  source url: \"http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-#{version}.tar.gz\",\n         md5: \"604da71839a6ae02b5b5b5e1b792d5eb\"\nend\n\nversion \"2.1.1\" do\n  source url: \"http://ftp.ruby-lang.org/pub/ruby/2.1/ruby-#{version}.tar.gz\",\n         md5: \"e57fdbb8ed56e70c43f39c79da1654b2\"\nend\n```\n\nSince the software definitions are simply ruby code, you can conditionally execute anything by wrapping it with pure Ruby that tests for the version number.\n\n#### Sharing software definitions\n\nThe easiest way to share organization-wide software is via bundler and Rubygems. For an example software repository, look at Chef's [omnibus-software](https://github.com/chef/omnibus-software). For more information, please see the [Rubygems documentation](http://guides.rubygems.org/publishing/).\n\nIt is recommended you use bundler to pull down these gems (as bundler also permits pulling software directly from GitHub):\n\n```ruby\ngem 'my-company-omnibus-software'\ngem 'omnibus-software', github: 'my-company/omnibus-software'\n```\n\nThen add the name of the software to the list of `software_gems` in your Omnibus config:\n\n```ruby\nsoftware_gems %w(my-company-omnibus-software omnibus-software)\n```\n\nYou may also specify local paths on disk (but be warned this may make sharing the project among teams difficult):\n\n```ruby\nlocal_software_dirs %w(/path/to/software /other/path/to/software)\n```\n\nFor all of these paths, **order matters**, so it is possible to depend on local software version while still retaining a remote software repo. Given the above example, Omnibus will search for a software definition named `foo` in this order:\n\n```text\n$PWD/config/software/foo.rb\n/path/to/software/config/software/foo.rb\n/other/path/to/software/config/software/foo.rb\n/Users/sethvargo/.gems/.../my-company-omnibus-software/config/software/foo.rb\n/Users/sethvargo/.gems/.../omnibus-software/config/software/foo.rb\n```\n\nThe first instance of `foo.rb` that is encountered will be used. Please note that **local** (vendored) softare definitions take precedence!\n\n## Building\n\nOnce you've created your package and software definitions you can build with:\n\n```shell\n./bin/omnibus build $MY_PACKAGE_NAME\n```\n\nHowever there are several caveats to be aware of:\n\n1. You will almost certainly want to uncomment the `base_dir` in `omnibus.rb`,\nor at the very least change `cache_dir` and `build_dir` as otherwise it'll try\nto use `/var/cache/omnibus` and `/opt/$MY_PROJECT_NAME`, requiring root.\n1. Update software dependencies listed in the project configuration in `config/projects/$MY_PROJECT_NAME.rb`. \nYou can refer the software `.rb` files present in the `config/software` folder.\n1. The `install_dir` specified in the project file typically requires `root` privilege at build time. \nChange it another location such as `\"/tmp/#{name}\"` to avoid running as `root`.\n1. The default configuration created for you references a lot of things\nthat are in the default config that come from the `omnibus-software` gem.\nSo you want to use those you'll need to either uncomment it in the `Gemfile`,\nor fork it, and then reference your own\n1. If this is a ruby project and you want binstubs in `/opt/$project/bin`, you\nwill either need to use [appbundler](https://github.com/chef/appbundler), or\nyou will need to have a post install step to create those binstubs.\n    - Side note, appbundler requires that you include your Gemfile and gemspec\n      in your gem.\n    - Also, needs to be in your Gemfile for you to use it, as it also must\n      be in the resulting gem.\n1. If you specify an override of the version of the `ruby`, you will also need\nto override `rubygems` and `bundler` to match the versions in that version of\n`ruby` or you'll get failures around bundler version mismatches.\n\nThe build command above will of course build on your local host thus being\nspecific to the OS and base system you are on. But the skeleten setup by\n`omnibus new` already setup kitchen for you so that it's easy to build for\na variety of OSes, See the `README.md` in your generated omnibus directory\nfor details.\n\n## Version Manifest\n\nGit-based software definitions may specify branches as their default_version. In this case, the exact git revision to use will be determined at build-time unless a project override (see below) or external version manifest is used. To generate a version manifest use the `omnibus manifest` command:\n\n```\nomnibus manifest PROJECT -l warn\n```\n\nThis will output a JSON-formatted manifest containing the resolved version of every software definition.\n\n## Whitelisting Libraries\n\nSometimes a platform has libraries that need to be whitelisted so the healthcheck can pass. The whitelist found in the [healthcheck](https://github.com/chef/omnibus/blob/master/lib/omnibus/health_check.rb) code comprises the minimal required for successful builds on supported platforms.\n\nTo add your own whitelisted library, simply add a regex to your software definition in your omnibus project as follows:\n\n```\nwhitelist_file /libpcrecpp\\.so\\..+/\n```\n\nIt is typically a good idea to add a conditional to whitelist based on the specific platform that requires it.\n\n_Warning: You should only add libraries to the whitelist that are guaranteed to be on the system you install to; if a library comes from a non-default package you should instead build it into the package._\n\n## Changelog\n\nSTATUS: _EXPERIMENTAL_\n\n`omnibus changelog generate` will generate a changelog for an omnibus project. This command currently assumes:\n\n- A version-manifest.json file is checked into the project root\n- The project is a git repository\n- Each version is tagged with a SemVer compliant annotated tag\n- Any git-based sources are checked out at ../COMPONENT_NAME\n- Any commit message line prepended with ChangeLog-Entry: should be added to the changelog\n\nThese assumptions _will_ change as we determine what works best for a number of our projects.\n\n## Caveats\n\n### Overrides\n\nThe project definitions can override specific software dependencies by passing in `override` to use the correct version:\n\n```ruby\nname \"chef-full\"\n# \u003csnip\u003e\n\n# This will override the default version of \"chef\"\noverride :chef, version: \"2.1.1\"\n\ndependency \"chef\"\n```\n\n**The overridden version must be defined in the associated software!**\n\n### Debugging\n\nBy default, Omnibus will log at the `warn` level. You can override this by passing the `--log-level` flag to your Omnibus call:\n\n```shell\n$ bin/omnibus build \u003cproject\u003e --log-level info # or \"debug\"\n```\n\n### Git caching\n\nby default, Omnibus caches compiled software definitions, so n+1 Omnibus project builds are much faster. This functionality can be disabled by adding the following to your `omnibus.rb`:\n\n```ruby\nuse_git_caching false\n```\n\n## Contributing\n\nFor information on contributing to this project see \u003chttps://github.com/chef/chef/blob/master/CONTRIBUTING.md\u003e\n\n## License\n\n```text\nCopyright 2012-2016 Chef Software, Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n[appveyor]: https://ci.appveyor.com/project/chef/omnibus\n[gem]: https://rubygems.org/gems/omnibus\n[travis]: https://travis-ci.org/chef/omnibus\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchef%2Fomnibus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchef%2Fomnibus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchef%2Fomnibus/lists"}