### dev-lxc.yml Config Files

dev-lxc uses a YAML configuration file named `dev-lxc.yml` to define a cluster.

The `init` command generates sample config files for various server types. You can run `dl help init` to see the many types of server configurations that can be generated.

The `--base-container` option can be used to set the type of base container you want used in the generated configuration.

The `--product-versions` option can be used to set the package channel and version to use for multiple products. If a version is not specified then it will default to `latest`. If `none` is used then that product will be removed from the generated configuration.

For example, the following command will generate a configuration for a standalone Chef Server that uses the `b-centos-7` base container and install chef-server 12.13.0 from the `stable` channel, the latest version of manage from the `current` channel and remove the reporting product.

```
dl init --chef --base-container b-centos-7 --product-versions chef-server:stable:12.13.0 manage:current reporting:none
```

Let's generate a config for a cluster with a standalone Chef Server, Supermarket server,
Compliance server, Chef Automate server and a Job Dispatch Runner and remove the "reporting" product from the generated configuration.

```
dl init --chef --compliance --supermarket --automate --runners --product-versions reporting:none > dev-lxc.yml
```

We can easily append additional configurations to this file. For example, the following command appends an infrastructure node.

```
dl init --nodes -a >> /root/work/clusters/automate/dev-lxc.yml
```

The contents of `dev-lxc.yml` should look like this.

```
# enable_build_snapshots automatically makes container snapshots at key times during the build process
# default value is `true`
#enable_build_snapshots: true

# base_container must be the name of an existing container
base_container: b-ubuntu-1404

# memory_per_server sets the maximum amount of user memory (including file cache) for each server.
# dev-lxc will set the `memory.limit_in_bytes` cgroup for each server to apply this limit.
# If no units are specified, the value is interpreted as bytes.
# You can use suffixes to represent larger units - k or K for kilobytes, m or M for megabytes, and g or G for gigabytes.
# The default behavior is that no limit is set.
#memory_per_server: 4G

# list any host directories you want mounted into the servers
#mounts:
#  - /root/clusters root/clusters

# list any SSH public keys you want added to /home/dev-lxc/.ssh/authorized_keys
#ssh-keys:
#  - /root/clusters/id_rsa.pub

# DHCP reserved (static) IPs must be selected from the IP range 10.0.3.150 - 254

chef-server:
  users:          # a user's password will be the same as its username
    - mary-admin
    - joe-user
  orgs:
    demo:
      admins:
        - mary-admin
      non-admins:
        - joe-user
  servers:
    chef.lxc:
      ipaddress: 10.0.3.203
      products:
        chef-server:
          channel: stable
          version: latest
        manage:
          channel: stable
          version: latest
        push-jobs-server:
          channel: stable
          version: latest

compliance:
  admin_user: admin         # the password will be the same as the username
  servers:
    compliance.lxc:
      ipaddress: 10.0.3.205
      products:
        compliance:
          channel: stable
          version: latest

supermarket:
  servers:
    supermarket.lxc:
      ipaddress: 10.0.3.206
      products:
        supermarket:
          channel: stable
          version: latest

automate:
  servers:
    automate.lxc:
      ipaddress: 10.0.3.200
      products:
        automate:
          channel: stable
          version: latest
      license_path: ../delivery.license
      chef_org: automate
      enterprise_name: default

runners:
  servers:
    runner-1.lxc:
      products:
        chefdk:     # downloaded only
          channel: stable
          version: latest

nodes:
  chef_server_url: https://chef.lxc/organizations/demo
  validation_client_name: demo-validator
  # comment out or remove the validation_key path to use chef-server keys generated by dev-lxc
  validation_key: # /path/for/ORG-validator.pem
  servers:
    node-1.lxc:
      products:
        chef:
          channel: stable
          version: latest

```

The dev-lxc.yml config file is very customizable. You can add or remove mounts, products or servers,
change ip addresses, server names, the base_container and more.

As you can see there are six server types represented by six servers.

1. chef-server - chef.lxc
2. compliance - compliance.lxc
3. supermarket - supermarket.lxc
4. automate - automate.lxc
5. runners - runner-1.lxc
6. nodes - node-1.lxc

#### Global Settings

The global settings used by each of the server types are `enable_build_snapshots`, the `base_container`, `memory_per_server`, a list of `mounts` and a list of `ssh-keys`. These settings are described in the config comments.

Be sure to set `base_container` in the `dev-lxc.yml` to an existing container's name.  
This container will be cloned to create each container in the cluster.  
If you don't already have a container to use as a `base_container` then you can follow the instructions in the  
[Create a dev-lxc Base Container section](https://github.com/jeremiahsnapp/dev-lxc#create-a-dev-lxc-base-container) to create one.

#### Server Specific Settings

It is possible to define different values for `enable_build_snapshots`, `base_container`, `memory_per_server`, `mounts` or `ssh-keys` for a particular server type or even for a particular server as you can see in the following snippet.

```
nodes:
  base_container: b-ubuntu-1404
  servers:
    node-1.lxc:
      base_container: b-centos-6
    node-2.lxc:
```

IP addresses from the range 10.0.3.150 - 254 can be assigned to the servers. If an IP address
is not specified then a dynamic IP address is assigned when the server starts.

#### mixlib-install Library Automatically Manages a Cache of Product Packages

dev-lxc uses the [mixlib-install](https://github.com/chef/mixlib-install) library to download Chef products
to a cache in `/var/dev-lxc` in the host instance. This cache is automatically mounted into each server when it starts.

A list of Chef products to be installed can be defined for each server
using [product names that mixlib-install understands](https://github.com/chef/mixlib-install/blob/master/PRODUCT_MATRIX.md).

The channel and version of the product can be defined also.

Channel can be `current`, `stable` or `unstable` with `stable` as the default.
Version can be `latest` or a version number with `latest` as the default.

For example, the following specifies the `current` channel and version `0.16.1` of the `chefdk` product.

```
nodes:
  servers:
    node-1.lxc:
      products:
        chefdk:
          channel: current
          version: 0.16.1
```

The `package_source` setting can be used to specify a package file on disk.

```
nodes:
  servers:
    node-1.lxc:
      products:
        chefdk:
          package_source: /root/chefdk_0.16.1-1_amd64.deb
```

#### Chef Server Orgs/Users

When defining a Chef Server you can include organizations and users that will be automatically created and associated accordingly.

#### Specify Chef Server Predefined Full and Partial Configurations

The following options work for a standalone Chef Server, the backend and frontends of a tier Chef Server cluster and the frontends of a chef-backend HA Chef Server cluster.

The `chef-server.rb` option can be used to fill a Chef server's chef-server.rb with predefined content from a file.

The `chef-server.rb_partials` option can be used to append predefined content from multiple files to a Chef server's chef-server.rb file.

```
servers:
  chef.lxc:
    chef-server.rb: /path/to/a/full/configuration/file
    chef-server.rb_partials:
      - /path/to/a/partial/configuration/file
      - /path/to/another/partial/configuration/file
    ipaddress: 10.0.3.203
    products:
      chef-server:
        channel: stable
        version: latest
```

#### Specify Automate Server Predefined Full and Partial Configurations

The `delivery.rb` option can be used to fill an Automate server's delivery.rb with predefined content from a file.

The `delivery.rb_partials` option can be used to append predefined content from multiple files to an Automate server's delivery.rb file.

```
servers:
  automate.lxc:
    delivery.rb: /path/to/a/full/configuration/file
    delivery.rb_partials:
      - /path/to/a/partial/configuration/file
      - /path/to/another/partial/configuration/file
    ipaddress: 10.0.3.200
    products:
      automate:
        channel: stable
        version: latest
```

#### Automatic Integration Between Servers

dev-lxc knows how to automatically configure Chef Server standalone, Chef Server tier topology,
Chef Server HA 2.0 as well as Chef Automate, Chef Client, Analytics, Compliance and Supermarket.

If a Chef Automate server, Compliance server, Analytics server or Supermarket server is defined in the same config file as
a Chef Server then each server will automatically be integrated with that Chef Server.

If a node server with Chef Client or Chef DK installed is defined in the same config file as
a Chef Server then the Chef Client will automatically be configured to use that Chef Server.

Alternatively, values for `chef_server_url`, `validation_client_name` and `validation_key` can
be set in the config file either for all nodes or for each individual node.

```
nodes:
  chef_server_url: https://chef.lxc/organizations/demo
  validation_client_name: demo-validator
  # comment out or remove the validation_key path to use chef-server keys generated by dev-lxc
  validation_key: # /path/to/org/validation/key
  servers:
    node-1.lxc:
      products:
        chef:
```