<commit_before>shpkpr
======

[![Build Status](https://travis-ci.org/shopkeep/shpkpr.svg?branch=master)](https://travis-ci.org/shopkeep/shpkpr)

shpkpr is a tool for controlling and observing applications running on Mesos/Marathon. shpkpr is designed to provide a simple command-line interface to Marathon (similiar to the `heroku` command-line tool) for use both manually and with CI tools like jenkins.


## Features

- List all deployed applications
- Show detailed application info
- Scale application resources
- View/Modify application configuration
- Deploy applications (using Jinja2 templates)
- View/Tail application logs
- **TODO:** Run one-off commands inside the deployed environment (like `heroku run`)


## Installation

To install a release version of shpkpr from [PyPI](https://pypi.python.org), simply:

```bash
$ pip install shpkpr # NOTE: This won't actually work until our first release
```

If you prefer to use shpkpr from git (**WARNING:** May be unstable), then:

```bash
$ pip install -e git+https://github.com/shopkeep/shpkpr.git#egg=shpkpr
```


## Configuration

All configuration options and arguments are fully documented in the `--help` screen for each command, however, `shpkpr` additionally allows all options to be specified in environment variables with the prefix `SHPKPR_`.

For example, to avoid having to specify the Marathon API URL with each command, you could do:

```bash
$ export SHPKPR_MARATHON_URL=http://my.marathon.install.mydomain.com:8080
$ shpkpr list
myapp1
my-other-app
yet-another-app
```

Which is functionally equivalent to:

```bash
$ shpkpr --marathon_url=http://my.marathon.install.mydomain.com:8080 list
myapp1
my-other-app
yet-another-app
```

Options specified on the command line will always take precedence over those in the environment.


## Usage

`shpkpr` is fully self-documenting, and documentation for any command can be viewed by passing the `--help` parameter, e.g.:

```bash
$ shpkpr --help
Usage: shpkpr [OPTIONS] COMMAND [ARGS]...

  A tool to manage applications running on Marathon.

Options:
  --marathon_url TEXT      URL of the Marathon API to use.  [required]
  --mesos_master_url TEXT  URL of the Mesos master to use.  [required]
  -v, --verbose            Enables verbose mode.
  --help                   Show this message and exit.

Commands:
  config  Manage application configuration
  deploy  Deploy application from template.
  list    Lists all deployed applications
  logs    View/tail application logs.
  scale   Scale application resources.
  show    Show application details.
```

Or:

```bash
$ shpkpr config --help
Usage: shpkpr config [OPTIONS] COMMAND [ARGS]...

  Manage application configuration

Options:
  --help  Show this message and exit.

Commands:
  list   List application configuration.
  set    Set application configuration.
  unset  Unset application configuration.
```


## Development Setup

### Local environment setup

The easiest way to setup `shpkpr` for development purposes is to use `pip` and install the application in "editable" mode:

```bash
$ git clone git@github.com:shopkeep/shpkpr.git

# Assumes you have virtualenvwrapper installed
$ mkvirtualenv shpkpr
New python executable in shpkpr/bin/python2.7
Also creating executable in shpkpr/bin/python
Installing setuptools, pip, wheel...done.

(shpkpr)$ pip install --editable .
```

Changes in your working tree should then be available (from within the virtual environment) when you run `shpkpr`.

### Testing

`shpkpr` runs its tests using [tox](https://tox.readthedocs.org/en/latest/). To run the tests locally, simply:

```bash
$ tox
```

Or to run the tests against a specific version of Python, you can:

```bash
$ tox -e py27
$ tox -e py34
```

**NOTE:** In future, the tests will make use of [Docker](http://docker.com) to provide a consistent environment for testing and build purposes.


## Examples

All examples below assume that the `SHPKPR_MARATHON_URL` environment variable has been set appropriately.
<commit_msg>updated README to include instructions on how to run tests in Docker<commit_after>shpkpr
======

[![Build Status](https://travis-ci.org/shopkeep/shpkpr.svg?branch=master)](https://travis-ci.org/shopkeep/shpkpr)

shpkpr is a tool for controlling and observing applications running on Mesos/Marathon. shpkpr is designed to provide a simple command-line interface to Marathon (similiar to the `heroku` command-line tool) for use both manually and with CI tools like jenkins.


## Features

- List all deployed applications
- Show detailed application info
- Scale application resources
- View/Modify application configuration
- Deploy applications (using Jinja2 templates)
- View/Tail application logs
- **TODO:** Run one-off commands inside the deployed environment (like `heroku run`)


## Installation

To install a release version of shpkpr from [PyPI](https://pypi.python.org), simply:

```bash
$ pip install shpkpr # NOTE: This won't actually work until our first release
```

If you prefer to use shpkpr from git (**WARNING:** May be unstable), then:

```bash
$ pip install -e git+https://github.com/shopkeep/shpkpr.git#egg=shpkpr
```


## Configuration

All configuration options and arguments are fully documented in the `--help` screen for each command, however, `shpkpr` additionally allows all options to be specified in environment variables with the prefix `SHPKPR_`.

For example, to avoid having to specify the Marathon API URL with each command, you could do:

```bash
$ export SHPKPR_MARATHON_URL=http://my.marathon.install.mydomain.com:8080
$ shpkpr list
myapp1
my-other-app
yet-another-app
```

Which is functionally equivalent to:

```bash
$ shpkpr --marathon_url=http://my.marathon.install.mydomain.com:8080 list
myapp1
my-other-app
yet-another-app
```

Options specified on the command line will always take precedence over those in the environment.


## Usage

`shpkpr` is fully self-documenting, and documentation for any command can be viewed by passing the `--help` parameter, e.g.:

```bash
$ shpkpr --help
Usage: shpkpr [OPTIONS] COMMAND [ARGS]...

  A tool to manage applications running on Marathon.

Options:
  --marathon_url TEXT      URL of the Marathon API to use.  [required]
  --mesos_master_url TEXT  URL of the Mesos master to use.  [required]
  -v, --verbose            Enables verbose mode.
  --help                   Show this message and exit.

Commands:
  config  Manage application configuration
  deploy  Deploy application from template.
  list    Lists all deployed applications
  logs    View/tail application logs.
  scale   Scale application resources.
  show    Show application details.
```

Or:

```bash
$ shpkpr config --help
Usage: shpkpr config [OPTIONS] COMMAND [ARGS]...

  Manage application configuration

Options:
  --help  Show this message and exit.

Commands:
  list   List application configuration.
  set    Set application configuration.
  unset  Unset application configuration.
```


## Development Setup

### Local environment setup

The easiest way to setup `shpkpr` for development purposes is to use `pip` and install the application in "editable" mode:

```bash
$ git clone <EMAIL>:shopkeep/shpkpr.git

# Assumes you have virtualenvwrapper installed
$ mkvirtualenv shpkpr
New python executable in shpkpr/bin/python2.7
Also creating executable in shpkpr/bin/python
Installing setuptools, pip, wheel...done.

(shpkpr)$ pip install --editable .
```

Changes in your working tree should then be available (from within the virtual environment) when you run `shpkpr`.

### Testing

`shpkpr` runs its tests using [tox](https://tox.readthedocs.org/en/latest/). To run the tests locally, simply:

```bash
$ tox
```

Or to run the tests against a specific version of Python, you can:

```bash
$ tox -e py27
$ tox -e py34
```

If you have Docker installed, the tests can also be run in containers to test easily against different versions of Python:

```bash
# To test all supported versions of Python
$ make test

# To test only a single version of Python (PyPy in this case)
$ make test.pypy
```


## Examples

All examples below assume that the `SHPKPR_MARATHON_URL` environment variable has been set appropriately.

{'fraction_non_alphanumeric': 0.0899205864386072, 'fraction_numerical': 0.004153940134392181, 'mean_word_length': 4.090796019900497, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 1, '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': '5945962', 'n_tokens_mistral': 2461, 'n_tokens_neox': 2293, 'n_words': 978}