orchestration 0.5.14 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 291252425784215fed686a5bf414b115dbec55ebca6bcdb23b136d5c6816e195
-  data.tar.gz: d972df8f59a94eca1912911b4f662fc195fa154efe935d5b4c55aef41c7b61c7
+  metadata.gz: ca5c9bd9b0a391d077e39e8447c38483f7149c3435b150289d2bebee4ca951b9
+  data.tar.gz: '08d6fdbd61e22b9ab3b5f3367250c7adfa0ad65dfecccc128a1075db8e6a478c'
 SHA512:
-  metadata.gz: 8628b095acf09db5f22f9144c4224fdbd3b97d16b737c3269e9ba3db04ca5c91574c926f6ea6382d4e6daea8248a7e297dc81dba06d1a1818077584a1955bd9a
-  data.tar.gz: 666c46c274e7fe26828e35b2eaa0ff8455b3c6866611e91572f7ad08daff1476985944b41ccf2e6c37b02294256deb9739f1c8413308e72509b0baab6b815e56
+  metadata.gz: f07f4b6ad5d5ce98cf65f94ccc9ae6ae280fab784a1760ede004a0cecdc4c90294e781d585868da9784603fca08f7e530b87ad94bf886e9c6f4c78e48264e7f3
+  data.tar.gz: 2cf4176c26c23d05733a926a8d22871a0e801a35d7e4b5643e92d7adfdb6a7627b23ee37dd97c01250937ebb31a7c9d638a5902377b91d512a48bcf90e5a0d90

data/README.md

@@ -7,12 +7,14 @@ At its core _Orchestration_ is simply a `Makefile` and a set of `docker-compose.
 A typical _Rails_ application can be tested, built, pushed to _Docker Hub_, and deployed to _Docker Swarm_ with the following commands:
 
 ```bash
-make test build push
+make setup test build push
 make deploy manager=user@swarm.example.com env_file=/var/configs/myapp.env
 ```
 
 _Orchestration_ has been successfully used to build continuous delivery pipelines for numerous production applications with a wide range or requirements.
 
+See [upgrade guide](UPGRADE.md) if you are upgrading from `0.5.x` to `0.6.x`.
+
 ## Example
 
 The below screenshot demonstrates _Orchestration_ being installed in a brand new _Rails_ application with support for _PostgreSQL_ (via the _PG_ gem) and _RabbitMQ_ (via the _Bunny_ gem):
@@ -27,7 +29,7 @@ The below screenshot demonstrates _Orchestration_ being installed in a brand new
 Add _Orchestration_ to your Gemfile:
 
 ```ruby
-gem 'orchestration', '~> 0.5.14'
+gem 'orchestration', '~> 0.6.3'
 ```
 
 Install:
@@ -83,7 +85,7 @@ All `make` commands provided by _Orchestration_ (with the exception of `test` an
 e.g.:
 ```
 # Stop all test containers
-make stop env=test
+make stop RAILS_ENV=test
 ```
 
 The default value for `env` is `development`.
@@ -91,7 +93,7 @@ The default value for `env` is `development`.
 As with any `Makefile` targets can be chained together, e.g.:
 ```
 # Run tests, build, and push image
-make test build push
+make setup test build push
 ```
 
 ### Containers
@@ -113,7 +115,7 @@ make stop
 #### Interface directly with `docker-compose`
 
 ```bash
-$(make compose env=test) logs -f database
+$(make compose RAILS_ENV=test) logs -f database
 ```
 
 ### Images
@@ -192,21 +194,15 @@ A default `test` target is provided in your application's main `Makefile`. You a
 
 To launch all dependency containers, run database migrations, and run tests:
 ```bash
-make test
+make setup test
 ```
 
 The default `test` command can (and should) be extended. This command is defined in the root `Makefile` in the project and, by defaults, runs `rspec` and `rubocop`.
 
-To run only the `test` command, without test setup (i.e. without restarting containers etc.), pass the `light` option:
+To skip the setup step and just run tests (i.e. once test containers are up and running and ready for use) simply run:
 
 ```bash
-make test light=1
-```
-
-If you prefer to run tests manually (e.g. if you want to run tests for a specific file) then the `test-setup` target can be used:
-```bash
-make test-setup
-bundle exec rspec spec/my_class_spec.rb
+make test
 ```
 
 Note that _Orchestration_ will wait for all services to become fully available (i.e. running and providing valid responses) before attempting to run tests. This is specifically intended to facilitate testing in continuous integration environments.
@@ -220,22 +216,29 @@ ORCHESTRATION_RETRY_LIMIT # default: 15
 ORCHESTRATION_RETRY_INTERVAL # default: 10 [seconds]
 ```
 
-### (Local) Production
+### (Local) Deployment
 
-Run a production environment locally to simulate your deployment platform:
+Run a deployment environment locally to simulate your deployment platform:
 
+```bash
+make deploy manager=localhost
 ```
-make start env=production
-```
+
+Ensure you have passwordless _SSH_ access to your own workstation and that you have approved the host authenticity/fingerprint.
 
 #### Deploy to a remote swarm
 
 To connect via _SSH_ to a remote swarm and deploy, pass the `manager` parameter:
-```
+```bash
 make deploy manager=user@manager.swarm.example.com
 ```
 
-The file `orchestration/docker-compose.production.yml` is created automatically. This file will always be used for deployment, regardless of _Rails_ environment. Other environments should be configured using a separate [`.env` file](#env-file) for each environment.
+The file `orchestration/docker-compose.deployment.yml` is created automatically. This file will be used for all deployments, regardless of _Rails_ environment. Other environments should be configured using a separate [`.env` file](#env-file) for each environment. i.e. to deploy a staging environment, create a `staging.env` (for example), set `RAILS_ENV=staging` and run:
+```bash
+make deploy manager=user@manager.swarm.example.com env_file=staging.env
+```
+
+This way you can set different publish ports and other application configuration variables for each stage you want to deploy to.
 
 #### Roll back a deployment
 
@@ -254,11 +257,11 @@ The `project_name` parameter is also supported.
 
 #### Use a custom stack name
 
-The [_Docker_ stack](https://docs.docker.com/engine/reference/commandline/stack/) name defaults to the name of your repository (as defined in `.orchesration.yml`) and the _Rails_ environment, e.g. `anvil_production`.
+The [_Docker_ stack](https://docs.docker.com/engine/reference/commandline/stack/) name defaults to the name of your repository (as defined in `.orchesration.yml`) and the _Rails_ environment, e.g. `anvil_staging`.
 
 To override this default, pass the `project_name` parameter:
 ```
-make deploy project_name=acme_anvil_production
+make deploy project_name=custom_stack_name
 ```
 
 This variable will also be available as `COMPOSE_PROJECT_NAME` for use within your `docker-compose.yml`. e.g. to explicitly name a network after the project name:
@@ -300,7 +303,7 @@ tail -f log/orchestration*.log
 A convenience `Makefile` target `dump` is provided. The following command will output all consumed _stdout_, _stderr_, and _Docker Compose_ container logs for the test environment:
 
 ```bash
-make dump env=test
+make dump RAILS_ENV=test
 ```
 
 All commands also support the `verbose` flag which will output all logs immediately to the console:
@@ -327,7 +330,7 @@ See related documentation:
 
 ## Healthchecks
 
-[Healthchecks](https://docs.docker.com/engine/reference/builder/#healthcheck) are automatically configured for your application. A healthcheck utility is provided in `orchestration/healthcheck.rb`. The following environment variables can be configured (in the `app` service of `orchestration/docker-compose.production.yml`):
+[Healthchecks](https://docs.docker.com/engine/reference/builder/#healthcheck) are automatically configured for your application. A healthcheck utility is provided in `orchestration/healthcheck.rb`. The following environment variables can be configured (in the `app` service of `orchestration/docker-compose.deployment.yml`):
 
 | Variable | Meaning | Default Value |
 |-|-|-|
@@ -355,7 +358,7 @@ Real-world applications will inevitably need to make changes to this file. As wi
 
 ## Entrypoint
 
-An [entrypoint](https://docs.docker.com/engine/reference/builder/#entrypoint) script for your application is provided which does the following:
+An [entrypoint](https://docs.docker.com/engine/reference/builder/#entrypoint) script for your application is provided at `orchestration/entrypoint.sh` which does the following:
 
 * Runs the `CMD` process as the same system user that launched the container (rather than the default `root` user);
 * Creates various required temporary directories and removes stale `pid` files;
@@ -370,7 +373,7 @@ If you need to start dependency services (databases, etc.) and connect to them f
 To do this automatically, pass the `sidecar` parameter to the `start` or `test` targets:
 
 ```bash
-make test sidecar=1
+make setup test sidecar=1
 ```
 
 When running in sidecar mode container-to-container networking is used so there is no benefit to binding dependency containers to a specific port on the host machine (only the target port will be used). For this reason a random, ephemeral port (chosen by _Docker_) will be used to allow multiple instances of each dependency to run alongside one another.
@@ -381,10 +384,10 @@ Note that a temporary file `orchestration/.sidecar` containing the random projec
 
 ```bash
 # Start dependencies and run tests in sidecar mode
-make test sidecar=1
+make setup test sidecar=1
 
 # Stop test dependencies in sidecar mode
-make stop env=test
+make stop RAILS_ENV=test
 ```
 
 <a name="rabbitmq-configuration"></a>

data/UPGRADE.md

@@ -0,0 +1,90 @@
+# Upgrade guide
+
+## 0.5 to 0.6
+
+### Delete/rename files
+
+Delete all files from `orchestration/` directory except:
+
+* `docker-compose.production.yml`
+* `docker-compose.development.yml`
+* `docker-compose.test.yml`
+* `Dockerfile`
+* `entrypoint.sh`
+
+Rename:
+
+```bash
+orchestration/docker-compose.production.yml => orchestration/docker-compose.deployment.yml
+```
+
+Any environment-specific compose files (e.g. `staging`) should also be removed as the same compose file is now used for all deployment stages.
+
+### Update Makefile
+
+Remove the first line of the main `Makefile` (in root of project) and replace it with the new `include` declaration:
+
+#### OLD
+
+```make
+include orchestration/Makefile
+```
+
+#### NEW
+
+```make
+include $(shell bundle exec ruby -e 'require "orchestration/make"')
+```
+
+#### Post-setup target
+
+Add a new target anywhere in the `Makefile` called `post-setup`:
+
+```make
+.PHONY: post-setup
+post-setup:
+	echo 'doing post setup stuff'
+```
+
+Replace the body of this target with any commands that you want to take place once the initial setup (launching development/test containers, running migrations, etc.) is complete. For example, running migrations for a secondary database.
+
+### Continuous Integration files
+
+Update any continuous integration scripts (e.g. `Jenkinsfile`) to run the `setup` target before `test`, e.g.:
+
+#### OLD
+
+```Jenkinsfile
+    stage('Test') {
+      steps {
+        sh 'make test sidecar=1'
+      }
+    }
+```
+
+#### NEW
+
+```Jenkinsfile
+    stage('Test') {
+      steps {
+        sh 'make setup test sidecar=1'
+      }
+    }
+```
+
+(`sidecar` may or may not be needed depending on your setup but, if it was there prior to upgrade, then it should remain after upgrade).
+
+### General Usage
+
+All _Orchestration_ commands behave exactly the same as before with the exception of the `test` target. Now, instead of running `make test` to launch all containers and then run tests, _Rubocop_, etc., you must run `make setup test`.
+
+This will set up the test environment and then run tests. You may then run `make test` to just run tests without having to go through the full setup process again.
+
+Similarly you can set up the development environment by just running `make setup`.
+
+To set up the test environment and run tests as two separate steps (i.e. equivalent of using the shorthand `make setup test`) you can run:
+
+```bash
+make setup RAILS_ENV=test
+make test
+```

data/config/locales/en.yml

@@ -1,33 +1,21 @@
 en:
   orchestration:
-    attempt_limit: "Unable to reconnect after %{limit} attempts. Aborting."
+    attempt_limit: "Unable to connect after %{limit} attempts. Aborting."
     default: "default"
     auto_update: "Orchestration Makefile was automatically updated to the latest version."
+    service:
+      ready: "%{service} is ready"
 
     app:
-      waiting: "Waiting for app: %{config}"
-      ready: "App is ready."
       connection_error: "Error attempting to connect to app: received status code %{code}"
 
     database:
-      waiting: "Waiting for database: %{config}"
-      ready: "Database is ready."
       unknown_environment: "Environment not defined in database configuration: %{environment}"
       unknown_adapter: "Unable to determine adapter from database.yml: %{adapter}"
 
     mongo:
-      waiting: "Waiting for Mongo: %{config}"
-      ready: "Mongo is ready."
       bad_config: "Unable to parse Mongo config: %{path}. Expected section for one of: %{expected}"
 
-    rabbitmq:
-      waiting: "Waiting for RabbitMQ: %{config}"
-      ready: "RabbitMQ is ready."
-
-    custom_service:
-      waiting: "Waiting for [%{service}]: %{config}"
-      ready: "[%{service}] is ready."
-
     settings:
       docker:
         organization:
@@ -44,3 +32,11 @@ en:
       install: "Install Orchestration tools"
       install_makefile: "(Re)create orchestration/Makefile"
       wait: "Wait for development/test dependencies to be available"
+      db:
+        url: "Return the database URL for the current environment (RAILS_ENV)"
+        console: "Launch a database console for the current environment (RAILS_ENV)"
+
+    dbconsole:
+      postgresql: "PGPASSWORD='%<password>s' psql --username=%<username>s --host=%<host>s --port=%<port>s --dbname=%<database>s"
+      sqlite3: "sqlite3 %<database>s"
+      mysql2: "mysql --user=%<username>s --port=%<port>s --host=%<host>s --password=%<password>s --no-auto-rehash %<database>s"

data/lib/orchestration/docker_compose/app_service.rb

@@ -99,6 +99,7 @@ module Orchestration
           'RAILS_SERVE_STATIC_FILES' => '1',
           'WEB_PRELOAD_APP' => '1',
           'WEB_HEALTHCHECK_PATH' => '/',
+          'WEB_PORT' => 8080,
           'DATABASE_URL' => database_url
         }.merge(inherited_environment.map { |key| [key, nil] }.to_h).merge(rabbitmq_urls)
       end

data/lib/orchestration/docker_compose/database_service.rb

@@ -34,7 +34,7 @@ module Orchestration
       end
 
       def networks
-        return {} unless @environment == :production
+        return {} unless @environment == :deployment
 
         { 'local' => { 'aliases' => ['database-local'] } }
       end

data/lib/orchestration/docker_compose/install_generator.rb

@@ -18,8 +18,8 @@ module Orchestration
         create_compose_file(:development)
       end
 
-      def docker_compose_production_yml
-        create_compose_file(:production)
+      def docker_compose_deployment_yml
+        create_compose_file(:deployment)
       end
 
       def enabled_services(environment)
@@ -68,7 +68,7 @@ module Orchestration
         case environment
         when :test, :development
           %i[database mongo rabbitmq]
-        when :production
+        when :deployment
           %i[app database mongo rabbitmq]
         when :local, nil
           []

data/lib/orchestration/install_generator.rb

@@ -27,30 +27,9 @@ module Orchestration
       @terminal.write(:skip, relpath)
     end
 
-    def verify_makefile(skip: true)
-      # Only run when called explicitly [from Rake tasks].
-      # (I know this is hacky).
-      return if skip
-
-      content = template('orchestration.mk', makefile_environment)
-      path = @env.orchestration_root.join('Makefile')
-      return if path.exist? && content == File.read(path)
-
-      write_file(path, content)
-      @terminal.write(:update, 'Makefile')
-      @terminal.write(:status, t(:auto_update))
-    end
-
     def application_makefile
       path = @env.root.join('Makefile')
       simple_copy('application.mk', path) unless File.exist?(path)
-      inject_if_missing(path, 'include orchestration/Makefile')
-    end
-
-    def orchestration_makefile
-      content = template('orchestration.mk', makefile_environment)
-      path = @env.orchestration_root.join('Makefile')
-      path.exist? ? update_file(path, content) : create_file(path, content)
     end
 
     def dockerfile
@@ -71,7 +50,7 @@ module Orchestration
     def docker_compose
       @docker_compose.docker_compose_test_yml
       @docker_compose.docker_compose_development_yml
-      @docker_compose.docker_compose_production_yml
+      @docker_compose.docker_compose_deployment_yml
     end
 
     def puma
@@ -133,14 +112,8 @@ module Orchestration
       I18n.t("orchestration.#{key}")
     end
 
-    def makefile_environment
-      macros = template('makefile_macros.mk', env: @env)
-
-      { env: @env, services: enabled_services, macros: macros }
-    end
-
     def enabled_services
-      %i[test development production].map do |environment|
+      %i[test development deployment].map do |environment|
         @docker_compose.enabled_services(environment)
       end.flatten.uniq
     end

data/lib/orchestration/make/orchestration.mk

@@ -0,0 +1,502 @@
+
+### Environment setup ###
+SHELL:=/bin/bash
+MAKE:=mkpath=${mkpath} make --no-print-directory
+
+TERM ?= 'dumb'
+pwd:=$(shell pwd)
+
+orchestration_dir_name=orchestration
+orchestration_dir=orchestration
+
+ifdef env_file
+  custom_env_file ?= 1
+else
+  custom_env_file ?= 0
+endif
+
+ifneq (,$(wildcard ${pwd}/config/database.yml))
+  database_enabled = 1
+else
+  database_enabled = 0
+endif
+
+red:=$(shell tput setaf 1)
+green:=$(shell tput setaf 2)
+yellow:=$(shell tput setaf 3)
+blue:=$(shell tput setaf 4)
+magenta:=$(shell tput setaf 5)
+cyan:=$(shell tput setaf 6)
+gray:=$(shell tput setaf 7)
+reset:=$(shell tput sgr0)
+tick=[${green}✓${reset}]
+cross=[${red}✘${reset}]
+
+make=$(MAKE) $1
+orchestration_config_filename:=.orchestration.yml
+orchestration_config:=${pwd}/${orchestration_config_filename}
+system_prefix=${reset}[${cyan}exec${reset}]
+warn_prefix=${reset}[${yellow}warn${reset}]
+echo_prefix=${reset}[${blue}info${reset}]
+fail_prefix=${reset}[${red}fail${reset}]
+logs_prefix=${reset}[${green}logs${reset}]
+system=echo '${system_prefix} ${cyan}$1${reset}'
+warn=echo '${warn_prefix} ${reset}$1${reset}'
+echo=echo '${echo_prefix} ${reset}$1${reset}'
+fail=echo '${fail_prefix} ${reset}$1${reset}'
+logs=echo '${logs_prefix} ${reset}$1${reset}'
+print_error=printf '${red}\#${reset} '$1 | tee '${stderr}'
+println_error=$(call print_error,$1'\n')
+print=printf '${blue}\#${reset} '$1
+println=$(call print,$1'\n')
+printraw=printf $1
+stdout=${pwd}/log/orchestration.stdout.log
+stderr=${pwd}/log/orchestration.stderr.log
+log_path_length=$(shell echo "${stdout}" | wc -c)
+ifndef verbose
+log_tee:= 2>&1 | tee -a ${stdout}
+log:= >>${stdout} 2>>${stderr}
+progress_point:=perl -e 'printf("[${magenta}busy${reset}] "); while( my $$line = <STDIN> ) { printf("."); select()->flush(); }'
+log_progress:= > >(tee -ai ${stdout} >&1 | ${progress_point}) 2> >(tee -ai ${stderr} 2>&1 | ${progress_point})
+endif
+hr=$(call println,"$1$(shell head -c ${log_path_length} < /dev/zero | tr '\0' '=')${reset}")
+managed_env_tag:=\# -|- ORCHESTRATION
+standard_env_path:=${pwd}/.env
+backup_env_path:=${pwd}/.env.orchestration.backup
+is_managed_env:=$$(test -f '${standard_env_path}' && tail -n 1 '${standard_env_path}') == "${managed_env_tag}"*
+token:=$(shell cat /dev/urandom | LC_CTYPE=C tr -dc 'a-z0-9' | fold -w8 | head -n1)
+back_up_env:=( \
+               [ ! -f '${standard_env_path}' ] \
+             || \
+               ( \
+                 [ -f '${standard_env_path}' ] \
+                 && cp '${standard_env_path}' '${backup_env_path}' \
+               ) \
+             )
+
+key_chars:=[a-zA-Z0-9_]
+censored:=**********
+censor=s/\(^${key_chars}*$(1)${key_chars}*\)=\(.*\)$$/\1=${censored}/
+censor_urls:=s|\([a-zA-Z0-9_+]\+://.*:\).*\(@.*\)$$|\1${censored}\2|
+format_env:=sed '$(call censor,SECRET); \
+                 $(call censor,TOKEN); \
+                 $(call censor,PRIVATE); \
+                 $(call censor,KEY); \
+                 $(censor_urls); \
+                 /^\s*$$/d; \
+                 /^\s*\#/d; \
+                 s/\(^[a-zA-Z0-9_]\+\)=/${blue}\1${reset}=/; \
+                 s/^/  /; \
+                 s/=\(.*\)$$/=${yellow}\1${reset}/' | \
+            sort
+
+exit_fail=( \
+           $(call printraw,' ${cross}') ; \
+           $(call make,dump src_cmd=$(MAKECMDGOALS)) ; \
+           echo ; \
+           $(call println,'Failed. ${cross}') ; \
+           exit 1 \
+        )
+
+ifdef env_file
+  -include ${env_file}
+else
+ifneq (${env},test)
+ifeq (,$(findstring test,$(MAKECMDGOALS)))
+  -include .env
+endif
+endif
+endif
+
+export
+
+ifneq (,$(findstring test,$(MAKECMDGOALS)))
+  env=test
+endif
+
+ifneq (,$(env))
+  # `env` set by current shell.
+else ifneq (,$(RAILS_ENV))
+  env=$(RAILS_ENV)
+else ifneq (,$(RACK_ENV))
+  env=$(RACK_ENV)
+else
+  env=development
+endif
+
+env_human=${gray}${env}${reset}
+DOCKER_TAG ?= latest
+
+ifneq (,$(wildcard ./Gemfile))
+  bundle_cmd = bundle exec
+endif
+rake=DEVPACK_DISABLE=1 RACK_ENV=${env} RAILS_ENV=${env} ${bundle_cmd} rake
+
+ifneq (,$(wildcard ${env_file}))
+  rake_cmd:=${rake}
+  rake=. ${env_file} && ${rake_cmd}
+endif
+
+docker_config:=$(shell DEVPACK_DISABLE=1 RAILS_ENV=development ${bundle_cmd} rake orchestration:config 2>/dev/null || echo no-org no-repo)
+docker_organization=$(word 1,$(docker_config))
+docker_repository=$(word 2,$(docker_config))
+
+ifeq (,$(project_name))
+  project_base = ${docker_repository}_${env}
+else
+  project_base := $(project_name)
+endif
+
+ifeq (,$(findstring deploy,$(MAKECMDGOALS)))
+  sidecar_suffix := $(shell test -f ${orchestration_dir}/.sidecar && cat ${orchestration_dir}/.sidecar)
+  ifneq (,${sidecar_suffix})
+    sidecar := 1
+  endif
+
+  ifdef sidecar
+    # Set the variable to an empty string so that "#{sidecar-1234}" will
+    # evaluate to "1234" in port mappings.
+    sidecar_compose = sidecar=''
+    ifeq (,${sidecar_suffix})
+      sidecar_suffix := $(call token)
+      _ignore := $(shell echo ${sidecar_suffix} > ${orchestration_dir}/.sidecar)
+    endif
+
+    ifeq (,${sidecar_suffix})
+      $(warning Unable to generate project suffix; project name collisions may occur.)
+    endif
+    compose_project_name = ${project_base}_${sidecar_suffix}
+  else
+    compose_project_name = ${project_base}
+  endif
+else
+  compose_project_name = ${project_base}
+endif
+
+compose_base=env -i \
+             PATH=$(PATH) \
+             HOST_UID=$(shell id -u) \
+             DOCKER_ORGANIZATION="${docker_organization}" \
+             DOCKER_REPOSITORY="${docker_repository}" \
+             COMPOSE_PROJECT_NAME="${compose_project_name}" \
+	     ${sidecar_compose} \
+             docker-compose \
+             -f ${orchestration_dir}/docker-compose.${env}.yml
+
+git_branch ?= $(if $(branch),$(branch),$(shell git rev-parse --abbrev-ref HEAD 2>/dev/null || echo no-branch))
+ifndef dev
+  git_version ?= $(shell git rev-parse --short --verify ${git_branch} 2>/dev/null || echo no-version)
+else
+  git_version = dev
+endif
+
+docker_image=${docker_organization}/${docker_repository}:${git_version}
+
+compose=${compose_base}
+compose_human=docker-compose -f ${orchestration_dir_name}/docker-compose.${env}.yml
+random_str=cat /dev/urandom | LC_ALL=C tr -dc 'a-z' | head -c $1
+
+ifneq (,$(wildcard ${orchestration_dir}/docker-compose.local.yml))
+  compose:=${compose} -f ${orchestration_dir}/docker-compose.local.yml
+endif
+
+all: build
+
+### Container management commands ###
+
+.PHONY: start
+ifndef network
+start: network := ${compose_project_name}
+endif
+start: _create-log-directory _clean-logs
+	@$(call system,${compose_human} up --detach)
+ifeq (${env},$(filter ${env},test development))
+	@${compose} up --detach --force-recreate --renew-anon-volumes --remove-orphans ${services} ${log} || ${exit_fail}
+	@[ -n '${sidecar}' ] && \
+         ( \
+           $(call echo,(joining dependency network ${cyan}${network}${reset})) ; \
+           $(call system,docker network connect "${network}") ; \
+           docker network connect '${network}' '$(shell hostname)' ${log} \
+           || ( \
+           $(call warn,Unable to join network: "${cyan}${network}${reset}". Container will not be able to connect to dependency services) ; \
+           $(call echo,Try deleting "${cyan}orchestration/.sidecar${reset}" if you do not want to use sidecar mode) ; \
+           ) \
+         ) \
+         || ( [ -z '${sidecar}' ] || ${exit_fail} )
+else
+	@${compose} up --detach --scale app=$${instances:-1} ${log} || ${exit_fail}
+endif
+	@$(call echo,${env_human} containers started ${tick})
+	@$(call echo,Waiting for services to become available)
+	@$(call make,wait) 2>${stderr} || ${exit_fail}
+
+.PHONY: stop
+stop: network := ${compose_project_name}
+stop:
+	@$(call echo,Stopping ${env_human} containers)
+	@$(call system,${compose_human} down)
+	@if docker ps --format "{{.ID}}" | grep -q $(shell hostname) ; \
+          then \
+            ( docker network disconnect ${network} $(shell hostname) ${log} || : ) \
+            && \
+            ( ${compose} down ${log} || ${exit_fail} ) ; \
+          else \
+            ${compose} down ${log} || ${exit_fail} ; \
+          fi
+	@$(call echo,${env_human} containers stopped ${tick})
+
+.PHONY: logs
+logs:
+	@${compose} logs -f
+
+.PHONY: config
+config:
+	@${compose} config
+
+.PHONY: compose
+compose:
+	@echo ${compose}
+
+### Development/Test Utility Commands
+
+.PHONY: serve
+serve: env_file ?= ./.env
+serve: rails = RAILS_ENV='${env}' bundle exec rails server ${server}
+serve:
+	@if [ -f "${env_file}" ] ; \
+         then ( \
+                $(call echo,Environment${reset}: ${cyan}${env_file}${reset}) && \
+                cat '${env_file}' | ${format_env} \
+            ) ; \
+        fi
+	${rails}
+
+.PHONY: console
+console: env_file ?= ./.env
+console: rails = RAILS_ENV='${env}' bundle exec rails
+console:
+	@if [ -f "${env_file}" ] ; \
+         then ( \
+                $(call echo,Environment${reset}: ${cyan}${env_file}${reset}) && \
+                cat '${env_file}' | ${format_env} \
+            ) ; \
+        fi
+	${rails} console
+
+.PHONY: db-console
+db-console:
+	@${rake} orchestration:db:console RAILS_ENV=${env}
+
+.PHONY: setup
+setup: url = $(shell ${rake} orchestration:db:url RAILS_ENV=${env})
+setup: _log-notify
+	@$(call echo,Setting up ${env_human} environment)
+	@$(call make,start env=${env})
+ifneq (,$(wildcard config/database.yml))
+	@$(call echo,Preparing ${env_human} database)
+	@$(call system,rake db:create DATABASE_URL="${url}")
+	@${rake} db:create RAILS_ENV=${env} ${log} || : ${log}
+  ifneq (,$(wildcard db/structure.sql))
+	@$(call system,rake db:schema:load DATABASE_URL="${url}")
+	@${rake} db:schema:load DATABASE_URL='${url}' ${log} || ${exit_fail}
+  else ifneq (,$(wildcard db/schema.rb))
+	@$(call system,rake db:schema:load DATABASE_URL="${url}")
+	@${rake} db:schema:load DATABASE_URL='${url}' ${log} || ${exit_fail}
+  endif
+	@$(call system,rake db:migrate DATABASE_URL="${url}")
+	@${rake} db:migrate RAILS_ENV=${env}
+endif
+	@$(MAKE) -n post-setup >/dev/null 2>&1 \
+          && $(call system,make post-setup RAILS_ENV=${env}) \
+          && $(MAKE) post-setup RAILS_ENV=${env}
+	@$(call echo,${env_human} environment setup complete ${tick})
+
+.PHONY: dump
+dump:
+ifndef verbose
+	@$(call println)
+	@$(call println,'${yellow}Captured${reset} ${green}stdout${reset} ${yellow}and${reset} ${red}stderr${reset} ${yellow}log data [${cyan}${env}${yellow}]${reset}:')
+	@$(call println)
+	@echo
+	@test -f '${stdout}' && ( \
+          $(call hr,${green}) ; \
+          $(call println,'${gray}${stdout}${reset}') ; \
+          $(call hr,${green}) ; \
+          echo ; cat '${stdout}' ; echo ; \
+          $(call hr,${green}) ; \
+        )
+
+	@test -f '${stdout}' && ( \
+          echo ; \
+          $(call hr,${red}) ; \
+          $(call println,'${gray}${stderr}${reset}') ; \
+          $(call hr,${red}) ; \
+          echo ; cat '${stderr}' ; echo ; \
+          $(call hr,${red}) ; \
+        )
+endif
+ifneq (build,${src_cmd})
+ifneq (push,${src_cmd})
+	@echo ; \
+        $(call hr,${yellow}) ; \
+        $(call println,'${gray}docker-compose logs${reset}') ; \
+        $(call hr,${yellow}) ; \
+        echo
+	@${compose} logs
+	@echo ; \
+        $(call hr,${yellow})
+	@$(NOOP)
+endif
+endif
+
+.PHONY: tag
+tag:
+	@echo ${docker_image}
+
+### Deployment utility commands ###
+
+.PHONY: deploy
+deploy: _log-notify _clean-logs
+ifdef env_file
+deploy: env_file_option = --env-file ${env_file}
+endif
+deploy: RAILS_ENV := ${env}
+deploy: RACK_ENV := ${env}
+deploy: DOCKER_TAG = ${git_version}
+deploy: base_vars = DOCKER_ORGANIZATION=${docker_organization} DOCKER_REPOSITORY=${docker_repository} DOCKER_TAG=${git_version}
+deploy: compose_deploy := ${base_vars} COMPOSE_PROJECT_NAME=${project_base} HOST_UID=$(shell id -u) docker-compose ${env_file_option} --project-name ${project_base} -f orchestration/docker-compose.deployment.yml
+deploy: config_cmd = ${compose_deploy} config
+deploy: remote_cmd = cat | docker stack deploy --prune --with-registry-auth -c - ${project_base}
+deploy: ssh_cmd = ssh "${manager}"
+deploy: deploy_cmd := ${config_cmd} | ${ssh_cmd} "/bin/bash -lc '${remote_cmd}'"
+deploy:
+ifndef manager
+	@$(call fail,Missing ${cyan}manager${reset} parameter: ${cyan}make deploy manager=swarm-manager.example.com${reset}) ; exit 1
+endif
+	@$(call echo,Deploying ${env_human} stack via ${cyan}${manager}${reset} as ${cyan}${project_base}${reset}) && \
+          ( \
+             ( test -f '${env_file}' && $(call echo,Deployment environment:) && cat '${env_file}' | ${format_env} || : ) && \
+             $(call echo,Application image: ${cyan}${docker_image}${reset}) ; \
+	     $(call system,${config_cmd} | ${ssh_cmd} "/bin/bash -lc '\''${remote_cmd}'\''") ; \
+	     ${deploy_cmd} \
+          )
+	@$(call echo,Deployment ${green}complete${reset} ${tick})
+
+.PHONY: rollback
+ifndef service
+rollback: service = app
+endif
+rollback:
+ifndef manager
+	@$(call fail,Missing `manager` parameter: `make deploy manager=swarm-manager.example.com`)
+	@exit 1
+endif
+	@$(call echo,Rolling back ${cyan}${compose_project_name}_${service}${reset} via ${cyan}${manager}${reset} ...)
+	@$(call system,docker service rollback --detach "${compose_project_name}_${service}")
+	@ssh "${manager}" 'docker service rollback --detach "${compose_project_name}_${service}"' ${log} || ${exit_fail}
+	@$(call echo,Rollback request ${green}complete${reset} ${tick})
+
+### Service healthcheck commands ###
+
+.PHONY: wait
+wait:
+	@${rake} orchestration:wait
+	@$(call echo,${env_human} services ${green}ready${reset} ${tick})
+
+## Generic Listener healthcheck for TCP services ##
+
+wait-listener:
+	@${rake} orchestration:listener:wait service=${service} sidecar=${sidecar}
+
+### Docker build commands ###
+
+.PHONY: build
+build: _log-notify _clean-logs
+build: build_dir = ${orchestration_dir}/.build
+build: context = ${build_dir}/context.tar
+build: build_args := --build-arg GIT_COMMIT='${git_version}'
+build: tag_human = ${cyan}${docker_organization}/${docker_repository}:${git_version}${reset}
+build: latest_tag_human = ${cyan}${docker_organization}/${docker_repository}:latest${reset}
+ifdef BUNDLE_GITHUB__COM
+build: build_args := ${build_args} --build-arg BUNDLE_GITHUB__COM
+endif
+ifdef BUNDLE_BITBUCKET__ORG
+build: build_args := ${build_args} --build-arg BUNDLE_BITBUCKET__ORG
+endif
+build: _create-log-directory check-local-changes
+	@$(call echo,Preparing build context from ${cyan}${git_branch}${reset} (${cyan}${git_version}${reset})${reset})
+	@$(call system,git archive --format "tar" -o "${context}" "${git_branch}")
+	@mkdir -p ${orchestration_dir}/.build ${log} || ${exit_fail}
+ifndef dev
+	@git show ${git_branch}:./Gemfile > ${orchestration_dir}/.build/Gemfile 2>${stderr} || ${exit_fail}
+	@git show ${git_branch}:./Gemfile.lock > ${orchestration_dir}/.build/Gemfile.lock 2>${stderr} || ${exit_fail}
+	@git archive --format 'tar' -o '${context}' '${git_branch}' ${log} || ${exit_fail}
+else
+	@tar -cvf '${context}' . ${log} || ${exit_fail}
+endif
+ifdef include
+	@$(call echo,Including files from: ${cyan}${include}${reset})
+	@(while read line; do \
+            export line; \
+            include_dir="${build_dir}/$$(dirname "$${line}")/" && \
+            mkdir -p "$${include_dir}" && cp "$${line}" "$${include_dir}" \
+            && (cd '${orchestration_dir}/.build/' && tar rf 'context.tar' "$${line}"); \
+	    echo "${system_prefix}" "tar rf 'context.tar' '$${line}'"; \
+          done < '${include}') ${log} || ${exit_fail}
+	@$(call echo,Build context ${green}ready${reset} ${tick})
+endif
+	@$(call echo,Building image ${tag_human})
+	@$(call system,docker build ${build_args} -t ${docker_organization}/${docker_repository}:${git_version} ${orchestration_dir}/)
+	@docker build ${build_args} \
+                        -t ${docker_organization}/${docker_repository}:${git_version} \
+                        ${orchestration_dir}/ ${log_progress} || ${exit_fail}
+	@echo
+	@$(call echo,Build ${green}complete${reset} ${tick})
+	@$(call echo,[${green}tag${reset}] ${tag_human})
+
+.PHONY: push
+push: _log-notify _clean-logs
+	@$(call echo,Pushing ${cyan}${docker_image}${reset} to registry)
+	@$(call system,docker push ${docker_image})
+	@docker push ${docker_image} ${log_progress} || ${exit_fail}
+	@echo
+	@$(call echo,Push ${green}complete${reset} ${tick})
+
+.PHONY: check-local-changes
+check-local-changes:
+ifndef dev
+	@changes="$$(git status --porcelain)"; if ! [ -z "${changes}" ] && [[ "${changes}" != "?? orchestration/.sidecar" ]]; \
+         then \
+           $(call warn,You have uncommitted changes which will not be included in your build:) ; \
+           git status --porcelain ; \
+           $(call echo,Commit these changes to Git or, alternatively, build in development mode to test your changes before committing: ${cyan}make build dev=1${reset}) ; \
+         fi
+endif
+
+### Internal Commands ###
+#
+.PHONY: _log-notify
+_log-notify: comma=,
+_log-notify: _verify-repository
+ifndef verbose
+	@$(call logs,${green}stdout${reset}: ${cyan}log/orchestration.stdout.log${reset}${comma} ${red}stderr${reset}: ${cyan}log/orchestration.stderr.log)
+endif
+
+.PHONY: _verify-repository
+_verify-repository:
+	@if ! git rev-parse HEAD >/dev/null 2>&1 ; then $(call fail,You must make at least one commit before you can use Orchestration commands) ; exit 1 ; fi
+
+.PHONY: _clean-logs
+_clean-logs:
+_clean-logs: _create-log-directory
+	@rm -f '${stdout}' '${stderr}'
+	@touch '${stdout}' '${stderr}'
+
+.PHONY: _create-log-directory
+_create-log-directory:
+	@mkdir -p log
+
+# Used by Orchestration test suite to verify Makefile syntax
+.PHONY: _test
+_test:
+	@echo 'test command'