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. (If you want to have a system config file, but somewhere besides ~/.broadside/config.rb, you can set the BROADSIDE_SYSTEM_CONFIG_FILE environment variable to a path of your choosing.)

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. Default us-east-1
• aws.credentials (REQUIRED) You can configure this manually by constructing an Aws::Credentials object OR it can be automatically constructed with the machine's default credentials. See [AWS Setup](AWS Setup) for more details on setting up your machine's default AWS credentials.
• ecs.cluster (REQUIRED) Name of the ECS cluster that will be the default deployment destination.
• ecs.poll_frequency Number of seconds in between polling ECS for deployment status updates. Default 2.
• application (REQUIRED) Name of your application
• docker_image (REQUIRED) Docker image that your application uses. Can be overridden on a per target basis. e.g. quay.io/mycompany/my_image
• 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: [['rake', 'db:migrate']]
  },
  my_second_target: {
    scale: 6,
    bootstrap_commands: [['rake', 'db:create']]
    ...
  }
}

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:

• bootstrap_commands Array of default commands to run when bootstrapping a new service and/or task_definition. Each command is itself an array so this is required to be an array of arrays.

• 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. Absolute paths are accepted as well as paths relative to broadside.config.rb. Broadside uses the Dotenv gem to load environment files into hashes.

• predeploy_commands Array of default commands to run in an instance of the application prior to performing the deploy. Each command is itself an array so this is required to be an array of arrays.

• scale (REQUIRED) How many instances of this container do you want to launch.

• service_config Accepts any valid AWS ECS service definition. Required for running bootstrap without an existing ECS Service. Minimal example:

  service_config: {
    deployment_configuration: {
      minimum_healthy_percent: 0.5,
    }
  }

• tag The git tag to default to when deploying this target, e.g. latest_tag.

• task_definition_config Accepts any valid AWS ECS task_definition. Required for running bootstrap without an existing AWS Task Definition. Minimal example:

  task_definition_config: {
    container_definitions: [
      {
        cpu: 1,
        memory: 2000,
      }
    ]
  }

Prepackaged Commands

There's a few commands that are used often enough that they are made available as convenience constants so you don't have to retype them, e.g.:

Broadside::Predeploy::RAKE_DB_MIGRATE

Hooks

• You can define your own pre and post hooks if you are using broadside from the command line. These procs will be executed 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.