Configuration

Configuring Broadside

It is recommended for you to wrap your configurations in a block like so:

Broadside.configure do |config|
  ...
end

By default, the CLI will assume the existence of a config/broadside.conf.rb file in your application root directory.

You may optionally place a ~/.broadside/config.rb global configuration file in your home directory. The global configuration will be used as a fallback, which is useful for defining ssh configs or other defaults that a specific application would not want to check in or that are shared across many applications on a machine.

List of Configurations

• aws.region AWS region that your infrastructure is hosted on.
• aws.credentials You can set this manually or it will be automatically constructed with the machine's default credentials as Aws::SharedCredentials.new.credentials
• ecs.cluster Name of ECS cluster for where to deploy the application
• ecs.poll_frequency Number of seconds in between polling ECS for deployment status updates.
• application Name of your application (required)
• docker_image Docker image that your application uses. Can be overridden on a per target basis.
• logger Any logger you want
• prehook See section on hooks
• posthook See section on hooks
• ssh SSH configurations to access instances in your cluster. Expects format:

config.ssh = {
  user: 'ssh_user',
  keyfile: 'path_to_keyfile',
  proxy: { # optionally specify a proxy host
    host: 'proxy_host',
    port: 'proxy_port'
  }
}

• timeout Number of seconds given for deployment until considered a failure.
• targets Your deploy targets (REQUIRED). See targets section for specifics. Expects format:

config.targets = {
  my_first_target: {
    scale: 2,
    env_file: '/some/path/.some.config',
    command: ['some', 'optional', 'command', 'to', 'run'],
    predeploy_commands: [
      'first_predeploy_command',
    ]
  },
  my_second_target: {
    scale: 6,
    ...
  }
}

Target Configuration

Targets can be configured independently of each other and also overload some higher level config on a case by case basis. Each target consists of a hash and can have the following keys configured:

• scale How many instances of this container do you want to launch (REQUIRED)
• bootstrap_commands List of default commands to run when bootstrapping a new service or task_definition
• cluster: Overrides ecs.cluster for a target
• command Default command to use when starting service
• docker_image: Overrides main configuration docker_image
• env_files String (or array containing strings - last entry in the array has precedence) pointing to files on the local machine containing key-value mapping of environment variables that will be injected into the docker container. Broadside uses the Dotenv gem to load environment files into hashes.
• predeploy_commands List of default commands to run in an instance of the application prior to performing the deploy.
• service_config Accepts any valid AWS ECS service definition
• task_definition_config Accepts any valid AWS ECS task_definition

Hooks

• You can define your own prehooks and posthooks if you are using broadside from the command line.

• This can be useful if you need to perform some prerequisite actions or cleanup tasks.

• In your broadside.conf.rb, add the following:

  # optionally require external code, if you don't want logic in the configuration file
  require_relative '../deploy_prereqs'
  
  Broadside.configure do |config|
    config.prehook = proc do |param| # also supports config.base.posthook
      if param[:command] == :deploy && param[:subcommand] == :short
        DeployPrereqs.do_something
      else
      # ...
      end
    end
  end

• The prehook will be called immediately after command line arguments are parsed, and the posthook after a command runs successfully. Note that the posthook does not get called if there is an error during execution.

• If your hook needs access to the configuration, you may use Broadside.config to grab this object.