<commit_before># Lattice: Run Containerized Workloads

<table>
  <tr>
    <td>
      <a href="http://lattice.cf"><img src="https://raw.githubusercontent.com/cloudfoundry-incubator/lattice/master/docs/logos/lattice.png" align="left" width="200" ></a>
    </td>
    <td>
      Website: <a href="http://lattice.cf">http://lattice.cf</a><br>
      Mailing List: <a href="https://groups.google.com/a/cloudfoundry.org/forum/#!forum/lattice">Google Groups</a>
    </td>
  </tr>
</table>

Lattice is an open source project for running containerized workloads on a cluster. Lattice bundles up http load-balancing, a cluster scheduler, log aggregation/streaming and health management into an easy-to-deploy and easy-to-use package.

Lattice is based on a number of open source [Cloud Foundry](http://cloudfoundry.org) components:

- [Diego](https://github.com/cloudfoundry-incubator/diego-design-notes) schedules and monitors containerized workloads
- [Loggregator](https://github.com/cloudfoundry/loggregator) aggregates and streams application logs
- [Gorouter](https://github.com/cloudfoundry/gorouter) provides http load-balancing

## Deploy Lattice

A [local deployment](#local-deployment) of Lattice can be launched with Vagrant.

A scalable [cluster deployment](#clustered-deployment) of Lattice can be launched with Terraform.  We currently support [AWS](terraform/aws/README.md), [DigitalOcean](terraform/digitalocean/README.md), and [Google Cloud](terraform/google/README.md)

## Use Lattice

The [Lattice CLI `ltc`](https://github.com/cloudfoundry-incubator/lattice/tree/master/ltc) provides a command line interface for launching docker-based applications.

More complex workloads can be constructed and submitted directly to Lattice's Receptor API which is fully documented [here](https://github.com/cloudfoundry-incubator/receptor/blob/master/doc/README.md).

# Local Deployment

## Launching with Vagrant

Make sure you have [Vagrant](https://vagrantup.com/) installed (version 1.6 or better), then:

```bash
git clone https://github.com/cloudfoundry-incubator/lattice.git
cd lattice
git checkout <VERSION>
vagrant up
```

This spins up a virtual environment that is accessible at `192.168.11.11`.  Here, `VERSION` refers to the tagged version you wish to deploy.  These tagged versions are known to be stable.

Use the [Lattice CLI](https://github.com/cloudfoundry-incubator/lattice/tree/master/ltc) to target Lattice:

```bash
ltc target 192.168.11.11.xip.io
```

> NOTE: Ubuntu 14.04 LTS does not install a compatible version of vagrant by default. You can upgrade the version that you get out of the box by downloading the `.deb` file from [Vagrant](http://www.vagrantup.com/downloads.html).

## Using Different Providers

You can do this with either VirtualBox or VMware Fusion (version 7 or later):

Virtualbox:

```bash
vagrant up --provider virtualbox
```

VMware Fusion:
```bash
vagrant up --provider vmware_fusion
```

### Networking Conflicts

If you are trying to run both the VirtualBox and VMWare providers on the same machine,
you'll need to run them on different private networks (subnets) that do not conflict.

Set the System IP to an address that does not conflict with the host networking configuration by passing the
`LATTICE_SYSTEM_IP` environment variable to the vagrant up command:

```bash
LATTICE_SYSTEM_IP=192.168.80.100 vagrant up
ltc target 192.168.80.100.xip.io
```

## Miscellaneous

### Running Vagrant with a custom Lattice tar

By default, `vagrant up` will fetch the latest Lattice binary tarball.  To use a particular tarball:

```bash
VAGRANT_LATTICE_TAR_PATH=/path/to/lattice.tgz vagrant up
```

### Updating

Currently, Lattice does not support updating via provision. So to update, you have to destroy the box and bring it back up:

```bash
 vagrant destroy --force
 git pull
 vagrant up
```

### Manual install of Lattice

Follow these [instructions](docs/manual-install.html.md) to install a co-located Lattice cluster to a server that's already deployed. (e.g., vSphere)  

### Proxy configuration

Install the `vagrant-proxyconf` plugin as follows:

```bash
vagrant plugin install vagrant-proxyconf
```

Copy the following into `~/.vagrant.d/Vagrantfile`:

```
Vagrant.configure("2") do |config|
  if Vagrant.has_plugin?("vagrant-proxyconf")
    config.proxy.http     = "http://PROXY_IP:PROXY_PORT"
    config.proxy.https    = "http://PROXY_IP:PROXY_PORT"
    config.proxy.no_proxy = "localhost,127.0.0.1,.consul"
  end
end
```

Then proceed with `vagrant up`.

## Troubleshooting

### No such host errors

DNS resolution for `xip.io` addresses can sometimes be flaky, resulting in errors such as the following:

```bash
 ltc target 192.168.11.11.xip.io
 Error verifying target: Get http://receptor.192.168.11.11.xip.io/v1/desired_lrps:
 dial tcp: lookup receptor.192.168.11.11.xip.io: no such host
```

First, check your networking DNS settings. Local "forwarding DNS" servers provided by some home routers can have trouble resolving `xip.io` addresses. Try setting your DNS to point to your real upstream DNS servers, or alternatively try using [Google DNS](https://developers.google.com/speed/public-dns/) by using `8.8.8.8` and/or `8.8.4.4`.

Unfortunately `xip.io` itself also sometimes returns similar "no such host" errors. The recommended alternative is to follow the [dnsmasq instructions](docs/dnsmasq-readme.html.md), pass the `LATTICE_SYSTEM_DOMAIN` environment variable to the vagrant up command, and target using `lattice.dev` instead of `192.168.11.11.xip.io` to point to the cluster, as follows:

```
LATTICE_SYSTEM_DOMAIN=lattice.dev vagrant up
ltc target lattice.dev
```

### Miscellaneous

If you have trouble running `vagrant up --provider virtualbox` with the error

```
default: Warning: Remote connection disconnect. Retrying...<commit_msg>Add HTTP_PROXY environment variable to `vagrant up` proxy instructions.<commit_after># Lattice: Run Containerized Workloads

<table>
  <tr>
    <td>
      <a href="http://lattice.cf"><img src="https://raw.githubusercontent.com/cloudfoundry-incubator/lattice/master/docs/logos/lattice.png" align="left" width="200" ></a>
    </td>
    <td>
      Website: <a href="http://lattice.cf">http://lattice.cf</a><br>
      Mailing List: <a href="https://groups.google.com/a/cloudfoundry.org/forum/#!forum/lattice">Google Groups</a>
    </td>
  </tr>
</table>

Lattice is an open source project for running containerized workloads on a cluster. Lattice bundles up http load-balancing, a cluster scheduler, log aggregation/streaming and health management into an easy-to-deploy and easy-to-use package.

Lattice is based on a number of open source [Cloud Foundry](http://cloudfoundry.org) components:

- [Diego](https://github.com/cloudfoundry-incubator/diego-design-notes) schedules and monitors containerized workloads
- [Loggregator](https://github.com/cloudfoundry/loggregator) aggregates and streams application logs
- [Gorouter](https://github.com/cloudfoundry/gorouter) provides http load-balancing

## Deploy Lattice

A [local deployment](#local-deployment) of Lattice can be launched with Vagrant.

A scalable [cluster deployment](#clustered-deployment) of Lattice can be launched with Terraform.  We currently support [AWS](terraform/aws/README.md), [DigitalOcean](terraform/digitalocean/README.md), and [Google Cloud](terraform/google/README.md)

## Use Lattice

The [Lattice CLI `ltc`](https://github.com/cloudfoundry-incubator/lattice/tree/master/ltc) provides a command line interface for launching docker-based applications.

More complex workloads can be constructed and submitted directly to Lattice's Receptor API which is fully documented [here](https://github.com/cloudfoundry-incubator/receptor/blob/master/doc/README.md).

# Local Deployment

## Launching with Vagrant

Make sure you have [Vagrant](https://vagrantup.com/) installed (version 1.6 or better), then:

```bash
git clone https://github.com/cloudfoundry-incubator/lattice.git
cd lattice
git checkout <VERSION>
vagrant up
```

This spins up a virtual environment that is accessible at `192.168.11.11`.  Here, `VERSION` refers to the tagged version you wish to deploy.  These tagged versions are known to be stable.

Use the [Lattice CLI](https://github.com/cloudfoundry-incubator/lattice/tree/master/ltc) to target Lattice:

```bash
ltc target 192.168.11.11.xip.io
```

> NOTE: Ubuntu 14.04 LTS does not install a compatible version of vagrant by default. You can upgrade the version that you get out of the box by downloading the `.deb` file from [Vagrant](http://www.vagrantup.com/downloads.html).

## Using Different Providers

You can do this with either VirtualBox or VMware Fusion (version 7 or later):

Virtualbox:

```bash
vagrant up --provider virtualbox
```

VMware Fusion:
```bash
vagrant up --provider vmware_fusion
```

### Networking Conflicts

If you are trying to run both the VirtualBox and VMWare providers on the same machine,
you'll need to run them on different private networks (subnets) that do not conflict.

Set the System IP to an address that does not conflict with the host networking configuration by passing the
`LATTICE_SYSTEM_IP` environment variable to the vagrant up command:

```bash
LATTICE_SYSTEM_IP=192.168.80.100 vagrant up
ltc target 192.168.80.100.xip.io
```

## Miscellaneous

### Running Vagrant with a custom Lattice tar

By default, `vagrant up` will fetch the latest Lattice binary tarball.  To use a particular tarball:

```bash
VAGRANT_LATTICE_TAR_PATH=/path/to/lattice.tgz vagrant up
```

### Updating

Currently, Lattice does not support updating via provision. So to update, you have to destroy the box and bring it back up:

```bash
 vagrant destroy --force
 git pull
 vagrant up
```

### Manual install of Lattice

Follow these [instructions](docs/manual-install.html.md) to install a co-located Lattice cluster to a server that's already deployed. (e.g., vSphere)  

### Proxy configuration

Install the `vagrant-proxyconf` plugin as follows:

```bash
vagrant plugin install vagrant-proxyconf
```

Copy the following into `~/.vagrant.d/Vagrantfile`:

```
Vagrant.configure("2") do |config|
  if Vagrant.has_plugin?("vagrant-proxyconf")
    config.proxy.http     = "http://PROXY_IP:PROXY_PORT"
    config.proxy.https    = "http://PROXY_IP:PROXY_PORT"
    config.proxy.no_proxy = "localhost,127.0.0.1,.consul"
  end
end
```

Then proceed with `HTTP_PROXY=http://PROXY_IP:PROXY_PORT vagrant up`.

## Troubleshooting

### No such host errors

DNS resolution for `xip.io` addresses can sometimes be flaky, resulting in errors such as the following:

```bash
 ltc target 192.168.11.11.xip.io
 Error verifying target: Get http://receptor.192.168.11.11.xip.io/v1/desired_lrps:
 dial tcp: lookup receptor.192.168.11.11.xip.io: no such host
```

First, check your networking DNS settings. Local "forwarding DNS" servers provided by some home routers can have trouble resolving `xip.io` addresses. Try setting your DNS to point to your real upstream DNS servers, or alternatively try using [Google DNS](https://developers.google.com/speed/public-dns/) by using `8.8.8.8` and/or `8.8.4.4`.

Unfortunately `xip.io` itself also sometimes returns similar "no such host" errors. The recommended alternative is to follow the [dnsmasq instructions](docs/dnsmasq-readme.html.md), pass the `LATTICE_SYSTEM_DOMAIN` environment variable to the vagrant up command, and target using `lattice.dev` instead of `192.168.11.11.xip.io` to point to the cluster, as follows:

```
LATTICE_SYSTEM_DOMAIN=lattice.dev vagrant up
ltc target lattice.dev
```

### Miscellaneous

If you have trouble running `vagrant up --provider virtualbox` with the error

```
default: Warning: Remote connection disconnect. Retrying...
{'fraction_non_alphanumeric': 0.10870307167235495, 'fraction_numerical': 0.018430034129692834, 'mean_word_length': 4.62158273381295, 'pattern_counts': {'":': 0, '<': 37, '<?xml version=': 0, '>': 39, 'https://': 22, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 22, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4273206', 'n_tokens_mistral': 3893, 'n_tokens_neox': 3608, 'n_words': 1236}