chbuild

chbuild

chbuild is an open-source command line application written in Ruby. It's main purpose is to simplify web app development by running a site using Docker containers so you don't have to install Apache, PHP and PHP extensions on your own machine.

Requirements

• Ruby 2.3.0+
• Docker (for Mac see this)

Installation

• Install requirements (see above)
• gem install chbuild

Usage

• Create a .chbuild.yml file in the root of your repository
• Launch docker
• Run $ chbuild start to build the image, launch the MySQL container and the chbuild container
• Run $ chbuild restart to restart the chbuild container

When you run the start command the following will happen:

• chbuild builds a docker image with apache, php-fpm and a couple of PHP extensions and configure them to work together
• chbuild downloads and starts a MySQL container (of your choice or the latest one if undefined in the YAML)
• chbuild starts the chbuild container
• chbuild runs the init script
• You can access the site on localhost:8088
• If your root directory is empty chbuild will create an index.php file with a phpinfo inside

When you run the restart command the following will happen:

• chbuild checks if your image is up-to-date and builds a new one if needed
• chbuild kills the currently running chbuild container
• chbuild starts a new container and reruns the init script

The container

The following happens in the container when you start it:

• Export the specified envrionment variables (env section)
• Runs the commands from the before section
• Starts apache
• Starts php-fpm to keep alive the container

The .chbuild.yml

The build file consists of sections: version, use, before, env. The minimal YAML file for chbuild to work properly:

---
version: 1.0

Sections of the build file

version - [required]

Version of the build file. Currently this is the only required section.

Allowed values: 1.0

Example

---
version: 1.0

use - [optional]

Specify the MySQL and PHP versions you want to use.

PHP

Current default PHP version: 5.6.25

At the moment specifying a PHP version is not working (to be implemented soon).

MySQL

Default is the latest from Dockerhub

To connect:

• no username
• password is 'admin'
• host address: $MYSQL_PORT_3306_TCP_ADDR

Example

---
version: 1.0
use:
  mysql: 5.6.20

env - [optional]

Specify environment variables to use them in the before script or in your site

Example

---
version: 1.0
env:
  THE_ANSWER: 42
  DOCTOR: Who

before - [optional]

Run scrips before starting php-fpm.

Example

---
version: 1.0
before:
  - composer install

Example .chbuild.yml

---
version: 1.0
use:
  mysql: 5.6.20
env:
  YAML_DEFINED: envvar
  ANOTHER_ENV_VAR: CHBuild
before:
  - echo "Hello, $ANOTHER_ENV_VAR!<br />Generated at $(date)<br /> MySQL version $MYSQL_ENV_MYSQL_VERSION" > /www/index.php

Commands

$ chbuild help
Commands:
  chbuild --version, -V          # Current version
  chbuild delete [-CIM]  # Delete container, image or MySQL container(s)
  chbuild help [COMMAND]         # Describe available commands or one specific command
  chbuild log                    # Get container log
  chbuild restart                # Restart chbuild container
  chbuild start                  # Build and start everything
  chbuild validate               # Validate build definition file

Options:
  -v, [--verbose], [--no-verbose]
  -f, [--force]

Development

After checking out the repo, run bin/setup to install dependencies.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

• Fork the repo
• Commit your changes to your own repo on a separate branch
• Submit pull request

If you can, please use the provided EditorConfig file!

License

The gem is available as open source under the terms of the MIT License. See more in LICENSE.txt