Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


boxbilling (13) Versions 1.0.0

Installs and configures BoxBilling, invoice and client management software

cookbook 'boxbilling', '~> 1.0.0', :supermarket
cookbook 'boxbilling', '~> 1.0.0'
knife supermarket install boxbilling
knife supermarket download boxbilling
Quality 17%

BoxBilling Cookbook

Cookbook Version
Dependency Status
Code Climate
Build Status

Chef cookbook to install and configure BoxBilling, invoice and client management software.


Supported Platforms

This cookbook has been tested on the following platforms:

  • Amazon Linux
  • CentOS >= 6.0
  • Debian
  • Fedora
  • RedHat
  • Ubuntu

Please, let us know if you use it successfully on any other platform.

Required Cookbooks

Required Applications

  • Ruby 1.9.3 or higher.


Attribute Default Description
node['boxbilling']['version'] '4.19.1' BoxBilling version (See below for BoxBilling version 3 installation).
node['boxbilling']['download_url'] calculated BoxBilling download URL.
node['boxbilling']['required_packages'] %w(unzip) BoxBilling required packages.
node['boxbilling']['php_packages'] calculated BoxBilling required PHP packages.
node['boxbilling']['dir'] '/srv/www/boxbilling' BoxBilling installation directory.
node['boxbilling']['server_name'] node['fqdn'] BoxBilling server name.
node['boxbilling']['cron_enabled'] true Whether to enable BoxBilling cron job.
node['boxbilling']['headers'] {} BoxBilling HTTP headers to set as hash.
node['boxbilling']['ssl'] true Whether to enable SSL in BoxBilling.
node['boxbilling']['encrypt_attributes'] false Whether to encrypt BoxBilling attributes containing credential secrets.
node['boxbilling']['web_server'] 'apache' Web server to use: 'apache' or 'nginx'
node['boxbilling']['admin']['email'] calculated BoxBilling admin email.
node['boxbilling']['admin']['pass'] calculated BoxBilling admin password.
node['boxbilling']['config']['timezone'] 'America/New_York' BoxBilling timezone. See PHP supported timezones.
node['boxbilling']['config']['db_host'] 'localhost' BoxBilling database host.
node['boxbilling']['config']['db_name'] 'boxbilling' BoxBilling database name.
node['boxbilling']['config']['db_user'] 'boxbilling' BoxBilling database user.
node['boxbilling']['config']['db_password'] calculated BoxBilling database user password.
node['boxbilling']['config']['url'] calculated BoxBilling URL.
node['boxbilling']['config']['license'] nil BoxBilling license key (required). Go to BoxBilling order page to get a new license.
node['boxbilling']['config']['locale'] 'en_US' BoxBilling locale.
node['boxbilling']['config']['sef_urls'] false Whether to enable BoxBilling search engine friendly URLs.
node['boxbilling']['config']['debug'] calculated Whether to enable BoxBilling debug mode.
node['boxbilling']['api_config']['require_referer_header'] true Whether to enable require referer header in the API.
node['boxbilling']['api_config']['allowed_ips'] [] BoxBilling allowed IP addresses to access the API. Empty array will allow all IPs to access the API.
node['boxbilling']['api_config']['rate_span'] 3600 BoxBilling API time span for limit in seconds.
node['boxbilling']['api_config']['rate_limit'] 1000 BoxBilling API requests allowed per time span.
node['boxbilling']['mysql']['server_root_password'] calculated BoxBilling MySQL root password.
node['boxbilling']['mysql']['server_debian_password'] calculated BoxBilling MySQL debian user password.
node['boxbilling']['mysql']['server_repl_password'] calculated BoxBilling MySQL repl user password.

The HTTPS Certificate

This cookbook uses the ssl_certificate cookbook to create the HTTPS certificate. The namespace used is node['boxbilling']. For example:

node.default['boxbilling']['common_name'] = ''
node.default['boxbilling']['config']['license'] = '...' # BB_LICENSE key
include_recipe 'boxbilling'

See the ssl_certificate namespace documentation for more information.

Encrypted Attributes

This cookbook can use the encrypted_attributes cookbook to encrypt the secrets generated during the Chef Run. This feature is disabled by default, but can be enabled setting the node['boxbilling']['encrypt_attributes'] attribute to true. For example:

include_recipe 'encrypted_attributes::users_data_bag'
node.default['boxbilling']['encrypt_attributes'] = true
node.default['boxbilling']['config']['license'] = '...' # BB_LICENSE key
inclure_recipe 'boxbilling'

This will create the following encrypted attributes:

  • node['boxbilling']['admin']['pass']: BoxBilling admin password.
  • node['boxbilling']['mysql']['root']: MySQL root user password.
  • node['boxbilling']['mysql']['debian']: MySQL debian user password.
  • node['boxbilling']['mysql']['repl']: MySQL repl user password.
  • node['boxbilling']['config']['db_password']: MySQL BoxBilling user password.

Read the chef-encrypted-attributes gem documentation to learn how to read them.



Installs and configures BoxBilling. Including the MySQL server if set to localhost.


Installs the requirementes to use the boxbilling_api resource.


Installs MySQL server for BoxBilling.



This resource uses the BoxBilling v2 Admin API with some modifications:

  • Some paths has been normalized, the action has been removed from the path and the resource action is issued instead.
  • The update action is simulated for some objects that do not support it, using delete and create.
  • All the action names has been simplified to create, update and delete.

Note: Keep in mind that some API calls require self-generated/auto-incremented MySQL identifiers. So their use can become difficult sometimes.

boxbilling_api Actions

  • request (default): Sends a HTTP raw API request.
  • create: Sends a create action to the API object.
  • update: Sends an update action to the API object.
  • delete: Send a delete action to the API object.

boxbilling_api Parameters

Parameter Default Description
path name BoxBilling API relative path. For example: 'admin/product'.
data {} Data to send as hash.
debug calculated Whether to enable debug mode.
ignore_failure false Ignore API HTTP errors.


You need a valid BoxBilling license key to use this cookbook. You can get a new license in the BoxBilling order page.

Including in a Cookbook Recipe

You can simply include it in a recipe:

# in your recipe
node.default['boxbilling']['config']['license'] = '...' # BB_LICENSE key
include_recipe 'boxbilling'

Don't forget to include the boxbilling cookbook as a dependency in the metadata:

# metadata.rb
depends 'boxbilling'

Including in the Run List

Another alternative is to include it in your Run List:

  "name": "",
  "[...]": "[...]",
  "normal": {
    "boxbilling": {
      "config": {
        "license": "BB_LICENSE"
  "run_list": [

Installing BoxBilling 3

To install BoxBilling version 3, you must change the node['boxbilling']['download_url'] attribute.

You can use GitHub to download the release. For example:

node.default['boxbilling']['config']['license'] = '...' # BB_LICENSE key
node.default['boxbilling']['download_url'] = ''

include_recipe 'boxbilling::default'

boxbilling::default Recipe Usage Example

node.default['boxbilling']['config']['license'] = '...' # BB_LICENSE key
include_recipe 'boxbilling::default'

boxbilling::api Recipe Usage Example

include_recipe 'boxbilling::api'

boxbilling::mysql Recipe Usage Example

include_recipe 'boxbilling::mysql'

boxbilling_api Resource Usage Example

Below is a fairly complete real example:

# =============================================================================
# Products
# =============================================================================

# Disable "Domains registration and transfer" product
boxbilling_api 'admin/product Domains registration and transfer' do
  path 'admin/product'
    id: 1,
    status: 'disabled'
  action :update

# =============================================================================
# News
# =============================================================================

# Delete some default blog news
(1..3).each do |id|
  boxbilling_api "admin/news delete #{id}" do
    path 'admin/news'
    data id: id
    action :delete

# New blog post
# boxbilling_api 'admin/news' do
#   data(
#     id: 4,
#     content: 'Blog post content...',
#     title: 'My first blog post',
#     # image: '',
#     status: 'active'
#     # created_at: '2012-01-01',
#     # updated_at: '2012-01-01'
#   )
#   action :create
# end

# =============================================================================
# Knowledge Base
# =============================================================================

# Disable some default articles
(1..3).each do |id|
  boxbilling_api 'admin/kb/article #{id}' do
    path 'admin/kb/article'
      id: id,
      status: 'draft'
    action :update

# Create some categories
# boxbilling_api 'admin/kb/category 3' do
#   path 'admin/kb/category'
#   data(
#     id: 3,
#     title: 'New KB category',
#     description: 'New KB category content description'
#   )
#   action :create
# end

# Add some articles
# boxbilling_api 'admin/kb/article 4' do
#   path 'admin/kb/article'
#   data(
#     id: 4,
#     kb_article_category_id: 3,
#     title: 'My New Article',
#     status: 'active',
#     content: 'My article content...'
#   )
#   action :create
# end

# =============================================================================
# Configuration > Settings > Client
# =============================================================================

boxbilling_api 'admin/extension/config' do
    ext: 'mod_client',
    allow_signup: 1,
    require_email_confirmation: 1,
    allow_change_email: 1,
    required: %w(last_name country city state address_1 postcode phone)
  action :update

# =============================================================================
# Configuration > Settings > Currency settings
# =============================================================================

boxbilling_api 'admin/currency EUR' do
  path 'admin/currency'
    code: 'EUR',
    title: 'Euro',
    format: "{{price}} \u20AC"
  action :create

boxbilling_api 'admin/currency GBP' do
  path 'admin/currency'
    code: 'GBP',
    title: 'Pound Sterling',
    format: "\u00A3{{price}}"
  action :create

boxbilling_api 'admin/currency/set_default' do
  data code: 'EUR'

# =============================================================================
# Configuration > Settings > Email
# =============================================================================

boxbilling_api 'admin/email/batch_template_generate'

# Reset a template
# boxbilling_api 'admin/email/template_reset client_password_reset_approve' do
#   path 'admin/email/template_reset'
#   data code: 'mod_client_password_reset_approve'
# end

# Create a new template
# boxbilling_api 'admin/email/template 1' do
#   path 'admin/email/template'
#   data(
#     id: 1,
#     enabled: 1,
#     category: 'client',
#     action_code: 'mod_client_password_reset_approve',
#     subject: '[{{ }}] Password Changed',
#     content: '...'
#   )
#   action :create
# end

# Update an existing template
# boxbilling_api 'admin/email/template 1' do
#   path 'admin/email/template'
#   data(
#     id: 1,
#     enabled: 1,
#     subject: '[{{ }}] Password Changed',
#     content: <<-EOF
# {% filter markdown %}
# Dear {{ c.first_name }} {{ c.last_name }},
# As you requested, your password for our client area has now been reset.
# Your new login details are as follows:
# Login at: {{"login"|link}}?email={{ }}
# Email: {{ }}
# Password: {{ password }}
# To change your password to something more memorable, after logging in go to 
# Profile &gt; Change Password.
# Edit your profile at {{ "me"|link }}
# {{ guest.system_company.signature }}
# {% endfilter %}
#     EOF
#   )
#   action :update
# end

# Email settings
# boxbilling_api 'admin/extension/config mod_email' do
#   path 'admin/extension/config'
#   data(
#     ext: 'mod_email',
#     log_enabled: 1,
#     mailer: 'smtp', # sendmail | smtp
#     smtp_host: smtp_host,
#     smtp_port: 587,
#     smtp_username: smtp_username,
#     smtp_password: smtp_password,
#     smtp_security: 'tls',
#   )
#   action :update
# end

# =============================================================================
# Configuration > Settings > Invoice settings
# =============================================================================

# Set next invoice number
# IMPORTANT: this must be run only once, will cause duplicated invoice numbers
boxbilling_api 'admin/system/params invoice starting_number' do
  path 'admin/system/params'
  data invoice_starting_number: '1'
  action :nothing

boxbilling_api 'admin/system/params invoice settings' do
  path 'admin/system/params'
    invoice_issue_days_before_expire: 14,
    invoice_due_days: 5,
    invoice_auto_approval: 1,
    remove_after_days: 0,
    invoice_series: 'PRO-N',
    invoice_series_paid: 'N',
    # negative_invoice | credit_note | manual
    invoice_refund_logic: 'credit_note',
    funds_min_amount: 10,
    funds_max_amount: 200
  action :update
  notifies :update, 'boxbilling_api[admin/system/params invoice starting_number]'

# =============================================================================
# Configuration > Settings > Orders settings
# =============================================================================

boxbilling_api 'admin/extension/config mod_order' do
  path 'admin/extension/config'
    ext: 'mod_order',
    # from_expiration_date | from_today | from_greater
    order_renewal_logic: 'from_expiration_date',
    batch_suspend_reason: ''
  action :update

# =============================================================================
# Configuration > Settings > System settings
# =============================================================================

boxbilling_api 'admin/system/params system settings' do
  path 'admin/system/params'
    company_name: 'Testing Labs, Ltd',
    company_logo: '',
    company_email: '',
    company_tel: '1234567890',
    company_address_1: 'Somewhere',
    company_number: 'B12345678',
    company_vat_number: 'EU12345678',
    company_account_number: 'BANK-1234',
    company_signature: 'Testing signature'
  action :update

# =============================================================================
# Configuration > Domain registration/management
# =============================================================================

# Delete default domain TLD
boxbilling_api 'admin/servicedomain/tld' do
  data tld: '.com'
  action :delete

# =============================================================================
# Configuration > Payment gateways
# =============================================================================

boxbilling_api 'admin/invoice/gateway Custom' do
  path 'admin/invoice/gateway'
    id: 1,
    enabled: 0,
    test_mode: 0
  action :update

# boxbilling_api 'admin/invoice/gateway PayPal' do
#   path 'admin/invoice/gateway'
#   data(
#     id: 2,
#     enabled: 1,
#     config: {
#       email: paypal_email
#     },
#     accepted_currencies: %w(EUR USD GBP),
#     test_mode: 0
#   )
#   action :update
# end

boxbilling_api 'admin/invoice/gateway AlertPay' do
  path 'admin/invoice/gateway'
    id: 3,
    enabled: 0,
    test_mode: test_mode
  action :update

# =============================================================================
# Configuration > Tax
# =============================================================================

# Enable taxes
boxbilling_api 'admin/system/params taxes' do
  path 'admin/system/params'
  data tax_enabled: 1
  action :update

# It deletes all the taxes and regenerate them instead of checking if they
# previously exists. Notified by boxbilling_api[admin/invoice/tax]
boxbilling_api 'admin/invoice/tax_setup_eu' do
    name: 'VAT EU12345678',
    taxrate: 21
  action :nothing

boxbilling_api 'admin/invoice/tax' do
    id: 9, # important, must match tax id when usign auto generated/increment
    name: 'EU12345678',
    taxrate: 21,
    country: 'ES'
  action :create
  notifies :request, 'boxbilling_api[admin/invoice/tax_setup_eu]'



ChefSpec Matchers


Helper method for locating a boxbilling_api resource in the collection.

resource = chef_run.boxbilling_api('admin/system/params')
  .to notify('boxbilling_api[admin/system/params invoice starting_number]')


Assert that the Chef Run makes a boxbilling_api request.

expect(chef_run).to request_boxbilling_api(path)


Assert that the Chef Run makes a boxbilling_api create request.

expect(chef_run).to create_boxbilling_api(path)


Assert that the Chef Run makes a boxbilling_api update request.

expect(chef_run).to update_boxbilling_api(path)


Assert that the Chef Run makes a boxbilling_api delete request.

expect(chef_run).to delete_boxbilling_api(path)


Please do not hesitate to open an issue with any questions or problems.




License and Author

Author: Raul Rodriguez (
Author: Xabier de Zuazo (
Copyright: Copyright (c) 2015, Xabier de Zuazo
Copyright: Copyright (c) 2013-2015, Onddo Labs, SL.
License: Apache License, Version 2.0
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

boxbilling CHANGELOG

This file is used to list changes made in each version of the boxbilling cookbook.

v1.0.0 (2015-09-01)

  • Install BoxBilling 4 by default, adds node['boxbilling']['version'] attribute (breaking change).
  • Update chef links to use domain.
  • Update contact information and links after migration.
  • metadata: Add source_url and issues_url.

  • Documentation:

    • README:
    • Use markdown tables.
    • Improve description.
  • Testing:

    • Replace all bats integration tests by Serverspec and infrataster tests.
    • Fix already initialized constant warning.
    • Gemfile: Update RuboCop to 0.33.0.
    • Move ChefSpec tests to test/unit.
    • Add a Guardfile.
    • Rakefile: Add clean task.
    • Travis CI: Run tests on Ruby 2.2.

v0.9.0 (2015-05-19)

  • Add custom HTTP headers support in nginx.
  • Update RuboCop to version 0.31.0.

v0.8.0 (2015-03-13)

  • RecipeHelpers#boxbilling_upload_cookbook_file: Upload files to the root directory instead of bb-uploads (disallowed in robots.txt).

v0.7.0 (2015-02-23)

  • Fix boxbilling_api[admin/system/params] notifications.
  • Disable PHP inside bb-uploads and bb-data directories.

v0.6.0 (2015-02-13)

  • boxbilling_api:
    • Use returned id when updating after a create.
    • Fix method name typo.
    • Use passed args when reading list.
    • Improved handling of borderline cases.
    • Fix condition on same_item?.
    • Handle paths that have slug field.

v0.5.0 (2015-02-08)

  • Update boxbilling when 'download_url' points to a new version.
  • boxbilling_api: Add same_item? to compare primary keys, support for 'admin/email/template'.
  • Calculate debug mode.
  • Fix all RuboCop offenses (big code refactor).
  • README: Add codeclimate badge.

v0.4.1 (2015-01-21)

  • Fix disabling nginx default site.

v0.4.0 (2015-01-20)

  • Add nginx support.
  • Small improvements.
  • Unit tests against Chef 11 and 12.

v0.3.0 (2015-01-03)

  • htaccess: Fix Apache 2.4 support.
  • Fix Ubuntu 14 support.
  • Add Fedora and RedHat support.
  • Add integration tests.
  • Update to use ssl_certificate cookbook version 1.1.0.
  • metadata: Use pessimistic operator for cookbook versions.
  • Enable ChefSpec coverage.
  • Gemfile: Use foodcritic fixed version.
  • Update license year.

v0.2.1 (2014-12-25)

  • boxbilling_api: fix encrypted attributes decryption outside chef solo.

v0.2.0 (2014-12-18)

  • Add BoxBilling 4 support.
  • Remove node['boxbilling']['api_config']['enabled'] attribute from documentation.
  • Create writable directory recursively.
  • metadata:
    • Fix attribute types.
    • Lock database cookbook version.
  • Fix version regular expression.
  • Refactor ignore failure exception logic.
  • Homogenize license headers.
  • Add Vagrantfile.
  • ChefSpec matchers: Add boxbilling_api locator.
  • Unit tests integrated with should_not gem.
  • ChefSpec unit tests clean up.
  • Update ChefSpec tests to 4.1.
  • Gemfile: Update vagrant-wrapper gem to 2.
  • Berksfile: Document local_cookbook method.
  • Move test/kitchen/cookbooks/boxbilling_test to test/cookbooks/boxbilling_test.
  • Some small improvements.
    • Clean up examples.
    • Small improvements.

v0.1.1 (2014-11-13)

  • Attributes: disable ['encrypt_attributes'] by default.
  • Remove node['boxbilling']['api_config']['enabled'] attribute (not needed).
  • Rakefile: include kitchen only in integration tests.
  • Gemfile:
    • Update to Berksfile 3.
    • Use vagrant-wrapper gem.
    • Add integration groups and disable them in travis-ci.

v0.1.0 (2014-08-28)

  • Initial release of boxbilling

Collaborator Number Metric

1.0.0 failed this metric

Failure: Cookbook has 1 collaborators. A cookbook must have at least 2 collaborators to pass this metric.

Contributing File Metric

1.0.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must contain a file

Foodcritic Metric

1.0.0 failed this metric

FC066: Ensure chef_version is set in metadata: boxbilling/metadata.rb:1
FC069: Ensure standardized license defined in metadata: boxbilling/metadata.rb:1
FC072: Metadata should not contain "attribute" keyword: boxbilling/metadata.rb:1
FC074: LWRP should use DSL to define resource's default action: boxbilling/resources/api.rb:1
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any

No Binaries Metric

1.0.0 passed this metric

Testing File Metric

1.0.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must contain a file

Version Tag Metric

1.0.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must include a tag that matches this cookbook version number