Configuration

Configuring Broadside

Basically you do it like this:

Broadside.configure do |config|
  config.application = 'my_app'
  ...
end

By default, the CLI will assume the existence of a config/broadside.conf.rb file in your application root directory. You can also manually specify a config file for an individual execution with --config config/to/my/other/broadside.conf.rb.

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

• application (REQUIRED) Name of your application
• aws.credentials (REQUIRED) You can configure this manually by constructing an Aws::Credentials object OR it will 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.
• aws.region AWS region that your infrastructure is hosted on. Default us-east-1
• aws.ecs_default_cluster Name of the ECS cluster that will be the default deployment destination.
• aws.ecs_poll_frequency Number of seconds in between polling ECS for deployment status updates. Default 2.
• default_docker_image 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
    user: 'proxy_user',
    host: 'proxy_host',
    port: 'proxy_port',
    keyfile: 'path_to_proxy_keyfile',
  }
}

• 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 aws.ecs_default_cluster for a target.

• command Default command to use when starting service.

• docker_image: Overrides main configuration default_docker_image.

• env_files String (or array containing strings) pointing to file(s) 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. The files are loaded left to right, and so the last file in the list has precedence. 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,
      }
    ]
  }

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.

• Your proc will be able to access a hash that contains the following keys:

  • :command - Name of the broadside command currently being run
  • :subcommand - Name of the broadside subcommand (if available)
  • :options - GLI generated hash of command-line flags and switches for the current run
  • :args - Array of args for the current run

• You may also call Broadside.config.targets to get access to deploy target configurations.

• 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.