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.

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. See targets section for specifics. Expects format:

config.targets = {
  my_first_target: {
    scale: NUM,
    env_file: 'path_relative_to_conf_file_or_absolute_path',
    command: 'optional_command_to_pass_into_application_container',
    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: Default scale used if not specified in deploy targets (required)
• env_files String (or array containing strings - last entry in the array has precedence) pointing to key-value mapping of environment variables to inject in to the docker container.
• command Default command to use when starting service
• bootstrap_commands List of default commands to run when bootstrapping a new service or task_definition
• 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.