gettingstarted

Getting started

Initializing a new project

The coach init operation can be used to turn an existing project into a coach project. This command does nothing more than add a .coach folder, with coach settings into the current folder.

The init operation has three modes:

• default: add a default set of configurations to the existing project
• user: copy a settings template from ~/.coach/templates/{template} to the current project
• git: checkout a git project to the current path

Example usage:

1. Default init:

The default init operation puts a local .coach folder into the current directory, and populates it with some default settings. A user is expected to override the default settings, but these settings should produce a working container set if used directly (although the container and image names may conflict on your system.)

$/> coach init

Getting a project up and running

Preparing an initialized project

Once a project has been initialized, you should customize the following files to meet your needs:

.coach/conf.yml: general settings for the project .coach/nodes.yml: A list of nodes used for the project

Building and Pulling project nodes

Once the settings meet your needs, you can get all of your docker containers and images ready using the following sequence of commands:

$/> coach build
$/> coach pull
$/> coach create

Running and stopping project containers

At this point, you can start your docker container set using:

$/> coach start

You can stop the project containers using:

$/> coach stop

What to use for nodes

In coach, each node describes a scalable or named set of docker containers based off of a single image, and using nearly-identical docker settings.

Each node has it's own YAML map in the nodes.yml file.

There are four types of nodes:

1. build: only used to build an image that might be shared across other nodes;
2. volume: only provides volumes which other nodes might use (standard docker practice);
3. service: a full docker container that is expected to run in the background;
4. command: a full docker container that is expected to run in the foreground and terminate.

Node settings

A simple example of a volume node in the nodes.yml file looks like this:

	# Source volume container
	source:
		Type: volume
		Build: /docker/source

		Host:
			Binds:
				- app/source:/app/source

A complex scaled service node example:

	www:
		Type: service

		Instances: scale 3 6

		Config:
			Image: jamesnesbitt/wunder-nginx
			RestartPolicy: on-failure

			Hostname: "%PROJECT_%INSTANCE"
			Domainname: "%CONTAINER_DOMAIN"
			Env:
				- "DNSDOCK_ALIAS=%INSTANCE.%PROJECT.%CONTAINER_DOMAIN"

			ExposedPorts:
				80/tcp: {}
				443/tcp: {}

		Host:
			Links:
				- fpm:fpm.app
			VolumesFrom:
				- files
				- source

A more complex example of a command node:

	shell:
		Type: command

		Config:
			Image: jamesnesbitt/wunder-developer
			Tty: true
			Env:
				- "PLATFORMSH_CLI_API_TOKEN=%PLATFORMSH_CLI_API_TOKEN"
				- "BLACKFIRE_SERVER_ID=%BLACKFIRE_SERVER_ID"
				- "BLACKFIRE_SERVER_TOKEN=%BLACKFIRE_SERVER_TOKEN"

		Host:
			Binds:
				- ~/.ssh:/app/.ssh                    # use the host ssh keys
				- .coach/drush:/app/.drush            # drush settings and cache
				- .coach/platformsh:/app/.platformsh  # platformsh settings and session
				- app/source:/app/source              # keep the source folder as well so that we can do drush make and platform build
			Links:
				- db:db.app
				- redis:redis.app
				- elasticsearch:elasticsearch.app
				- blackfire:blackfire.app
			VolumesFrom:
				- source                              # get the webroot from the source container
				- files                               # get files from the files container

Tokens and secrets

Tokens are key-value pairs that can be used for substitution in configurations, to allow centralized configurations, instance based settings, and secret configurations to be used in a variable like syntax.

The following use cases are common:

• put a secret ID into the .coach/secrets/secrets.yml file, and refer to it in a node: Config: Env to make it available in a container as an environment variable.
• put a user token into ~/.coach/secrets/secrets.yml, so that a single setting can be used across all projects for all containers that use a single external service (like blackfire.)
• Configure a container hostname to refer to the name of the project, or the instance

Conf tokens

A common place to put tokens is into the .coach/conf.yml file in the Tokens: list. This makes the tokens available in any further load.

Secrets

Secrets are tokens that are loaded from files that can easily be excluded from any versioned source repository. There are two locations for secret tokens:

• ~/.coach/secrets/secrets.yml : user specific projects
• .coach/secrets/secrets.yml : project specific secrets