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.

Both these files are just raw ruby that will be evaluated, so you can do whatever you want in there as long as you have a Broadside.configure block.

Gem Level 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. See [AWS Setup](AWS Setup) for more details.
• ecs.cluster Name of the ECS cluster that will be the default deployment destination. (REQUIRED)
• 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. (REQUIRED)
• logger Set it to any ruby Logger you want.
• prehook See section on hooks.
• posthook See section on hooks.
• ssh SSH configurations to access instances in your cluster. Required if you need to use certs or particular settings to get to your instances. 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 to wait before deployment is considered a failure and rolled back.
• 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. Required for running bootstrap without an existing AWS Service.
• task_definition_config Accepts any valid AWS ECS task_definition. Required for running bootstrap without an existing AWS Task Definition.

Hooks

• You can define your own prehooks and posthooks if you are using broadside from the command line. These will be run on the local machine. This can be useful if you need to perform some prerequisite actions or cleanup tasks.

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

  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.