<commit_before>[![Gem Version](https://badge.fury.io/rb/dockly.png)](http://badge.fury.io/rb/dockly)
[![Build Status](https://travis-ci.org/swipely/dockly.png?branch=refactor_setup)](https://travis-ci.org/swipely/dockly)
[![Dependency Status](https://gemnasium.com/swipely/dockly.png)](https://gemnasium.com/swipely/dockly)

![Dockly](https://raw.github.com/swipely/dockly/master/img/dockly.png)
======================================================================

`dockly` is a gem made to ease the pain of packaging an application. For this gem to be useful, quite a few assumptions can be made about your stack:

- You're deploying to a Debian-based system
- You want to use [Docker](http://docker.io) for process isolation

Although only a specific type of repository may be used, these assumptions allow us to define a simple DSL to describe your repository.

Usage
-----

Once a `deb` block has been defined by the DSL below, dockly is invoked by either `bundle exec dockly build #{deb block name}` or `bundle exec rake dockly:deb:#{deb block name}`.

The DSL
-------

The DSL is broken down into multiple objects, all of which conform to a specific format. Each object starts with the name of the section,
followed by a name for the object you're creating, and a block for configuration.

```ruby
docker :test_docker do
  # code here
end
```

Each object has an enumeration of valid attributes. The following code sets the `repository` attribute in a `docker` called `test_docker`:

```ruby
docker :test_docker do
  repository 'an-awesome-name'
end
```

Finally, each object has zero or more valid references to other DSL objects. The following code sets `deb` that references a `docker`:

```ruby
docker :my_docker do
  repository 'my-name'
end

deb :my_deb do
  docker :my_docker
end
```

Below is an alternative syntax that accomplishes the same thing:

```ruby
deb :my_deb do
  docker do
    repository 'my-name'
  end
end
```

`build_cache`
-------------

Optional

The `build_cache` DSL is used to prevent rebuilding assets every build and used cached assets.

- `s3_bucket`
    - required: `true`
    - description: the bucket name to download and upload build caches to
- `s3_object_prefix`
    - required: `true`
    - description: the name prepended to the package; allows for namespacing your caches
- `hash_command`
    - required: `true`
    - description: command run to determine if the build cache is up to date (eg. `md5sum ... | awk '{ print $1 }'`)
- `parameter_command`
    - required: `false`
    - allows multiple
    - description: command run to build specific versions of build caches -- useful for multiple operating systems (not required)
- `build_command`
    - required: `true`
    - description: command run when the build cache is out of date
- `output_dir`
    - required: `true`
    - description: where the cache is located in the Docker image filesystem
- `tmp_dir`
    - required: `true`
    - default: `/tmp`
    - description: where the build cache files are stored locally; this should be able to be removed easily since they all exist in S3 as well
- `use_latest`
    - required: `false`
    - default: `false`
    - description: when using S3, will insert the S3 object tagged as latest in your "s3://s3_bucket/s3_object_prefix" before running the build command to quicken build times

`docker`
--------

The `docker` DSL is used to define Docker containers. It has the following attributes:

- `import`
    - required: `true`
    - description: the location (url or S3 path) of the base image to start building from
- `git_archive`:
    - required: `false`
    - default: `nil`
    - description: the relative file path of git repo that should be added to the container
- `build`
    - required: `true`
    - description: aditional Dockerfile commands that you'd like to pass to `docker build`
- `repository`
    - required: `true`
    - default: `'dockly'`
    - description: the repository of the created image
- `name`
    - alias for: `repository`
- `tag`
    - required: `true`
    - description: the tag of the created image
- `build_dir`
    - required: `true`
    - default: `./build/docker`
    - description: the directory of the temporary build files
- `package_dir`
    - required: `true`
    - default: `/opt/docker`
    - description: the location of the created image in the Debian package
- `timeout`
    - required: `true`
    - default: `60`
    - description: the excon timeout for read and write when talking to docker through docker-api
- `build_caches`
    - required: `false`
    - default: `[]`
    - description: a listing of references to build caches to run

In addition to the above attributes, `docker` has the following references:

- `build_cache`
    - required: `false`
    - allows multiple
    - class: `Dockly::BuildCache`
    - description: a caching system to stop rebuilding/compiling the same files every time

Need finer control of Docker packages? We also wrote [docker-api](https://github.com/swipely/docker-api).

`foreman`
---------

Optional

The `foreman` DSL is used to define the foreman export scripts. It has the following attributes:

- `env`
    - description: accepts same arguments as `foreman start --env`
- `procfile`
    - required: `true`
    - default: `'Procfile'`
    - description: the Procfile to use
- `type`
    - required: `true`
    - default: `'upstart'`
    - description: the type of foreman script being defined
- `user`
    - required: `true`
    - default: `'nobody'`
    - description: the user the scripts will run as
- `root_dir`<commit_msg>Add registries to the README.<commit_after>[![Gem Version](https://badge.fury.io/rb/dockly.png)](http://badge.fury.io/rb/dockly)
[![Build Status](https://travis-ci.org/swipely/dockly.png?branch=refactor_setup)](https://travis-ci.org/swipely/dockly)
[![Dependency Status](https://gemnasium.com/swipely/dockly.png)](https://gemnasium.com/swipely/dockly)

![Dockly](https://raw.github.com/swipely/dockly/master/img/dockly.png)
======================================================================

`dockly` is a gem made to ease the pain of packaging an application. For this gem to be useful, quite a few assumptions can be made about your stack:

- You're deploying to a Debian-based system
- You want to use [Docker](http://docker.io) for process isolation

Although only a specific type of repository may be used, these assumptions allow us to define a simple DSL to describe your repository.

Usage
-----

Once a `deb` block has been defined by the DSL below, dockly is invoked by either `bundle exec dockly build #{deb block name}` or `bundle exec rake dockly:deb:#{deb block name}`.

The DSL
-------

The DSL is broken down into multiple objects, all of which conform to a specific format. Each object starts with the name of the section,
followed by a name for the object you're creating, and a block for configuration.

```ruby
docker :test_docker do
  # code here
end
```

Each object has an enumeration of valid attributes. The following code sets the `repository` attribute in a `docker` called `test_docker`:

```ruby
docker :test_docker do
  repository 'an-awesome-name'
end
```

Finally, each object has zero or more valid references to other DSL objects. The following code sets `deb` that references a `docker`:

```ruby
docker :my_docker do
  repository 'my-name'
end

deb :my_deb do
  docker :my_docker
end
```

Below is an alternative syntax that accomplishes the same thing:

```ruby
deb :my_deb do
  docker do
    repository 'my-name'
  end
end
```

`build_cache`
-------------

Optional

The `build_cache` DSL is used to prevent rebuilding assets every build and used cached assets.

- `s3_bucket`
    - required: `true`
    - description: the bucket name to download and upload build caches to
- `s3_object_prefix`
    - required: `true`
    - description: the name prepended to the package; allows for namespacing your caches
- `hash_command`
    - required: `true`
    - description: command run to determine if the build cache is up to date (eg. `md5sum ... | awk '{ print $1 }'`)
- `parameter_command`
    - required: `false`
    - allows multiple
    - description: command run to build specific versions of build caches -- useful for multiple operating systems (not required)
- `build_command`
    - required: `true`
    - description: command run when the build cache is out of date
- `output_dir`
    - required: `true`
    - description: where the cache is located in the Docker image filesystem
- `tmp_dir`
    - required: `true`
    - default: `/tmp`
    - description: where the build cache files are stored locally; this should be able to be removed easily since they all exist in S3 as well
- `use_latest`
    - required: `false`
    - default: `false`
    - description: when using S3, will insert the S3 object tagged as latest in your "s3://s3_bucket/s3_object_prefix" before running the build command to quicken build times

`docker`
--------

The `docker` DSL is used to define Docker containers. It has the following attributes:

- `import`
    - required: `true`
    - description: the location (url or S3 path) of the base image to start building from
- `git_archive`:
    - required: `false`
    - default: `nil`
    - description: the relative file path of git repo that should be added to the container
- `build`
    - required: `true`
    - description: aditional Dockerfile commands that you'd like to pass to `docker build`
- `repository`
    - required: `true`
    - default: `'dockly'`
    - description: the repository of the created image
- `name`
    - alias for: `repository`
- `tag`
    - required: `true`
    - description: the tag of the created image
- `build_dir`
    - required: `true`
    - default: `./build/docker`
    - description: the directory of the temporary build files
- `package_dir`
    - required: `true`
    - default: `/opt/docker`
    - description: the location of the created image in the Debian package
- `timeout`
    - required: `true`
    - default: `60`
    - description: the excon timeout for read and write when talking to docker through docker-api
- `build_caches`
    - required: `false`
    - default: `[]`
    - description: a listing of references to build caches to run

In addition to the above attributes, `docker` has the following references:

- `build_cache`
    - required: `false`
    - allows multiple
    - class: `Dockly::BuildCache`
    - description: a caching system to stop rebuilding/compiling the same files every time
- `build_cache`
    - required: `false`
    - allows one
    - class: `Dockly::Docker::Registry`
    - description: a registry to push to in lieu of exporting as a tar -- the registry will be automatically pulled upon installing the debian package

Need finer control of Docker packages? We also wrote [docker-api](https://github.com/swipely/docker-api).

`registry`
--------

The `registry` DSL is used to define Docker Registries. It has the following attributes:

- `username`
    - required: `true`
    - description: the username to authenticate
- `email`:
    - required: `true`
    - description: the email to authenticate
- `password`:
    - required: `false`
    - description: the user's password; unless supplied, `ENV['DOCKER_REGISTRY_PASSWORD']` will be checked
- `server_address`:
    - required: `true`
    - default: `https://index.docker.io/v1`
    - description: the server where the registry lives

`foreman`
---------

Optional

The `foreman` DSL is used to define the foreman export scripts. It has the following attributes:

- `env`
    - description: accepts same arguments as `foreman start --env`
- `procfile`
    - required: `true`
    - default: `'Procfile'`
    - description: the Procfile to use
- `type`
    - required: `true`
    - default: `'upstart'`
    - description: the type of foreman script being defined
- `user`
    - required: `true`
    - default: `'nobody'`
    - description: the user the scripts will run as
- `root_dir`
{'fraction_non_alphanumeric': 0.11591174995821495, 'fraction_numerical': 0.002256393113822497, 'mean_word_length': 3.3771031455742504, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 15, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6898128', 'n_tokens_mistral': 3620, 'n_tokens_neox': 3424, 'n_words': 1430}