Cai::Ecs::Entrypoint

This gem provides an easy and convenient method for Docker-based applications to retrieve configuration as environment variables at application startup.

Installation

Add the following line to your application's Dockerfile as early as possible, preferrably following the FROM statement:

FROM some/base

# If necessary, install Ruby runtime; omit if container already includes Ruby, such as a Rails app
RUN apt-get update && apt-get -y install ruby

# Install cai-ecs-entrypoint gem
RUN gem install cai-ecs-entrypoint -v 1.1.0

Installing the Ruby runtime and gem early in the Docker file allows Docker container layer caching and will improve build times.

Usage

To use the gem, alter your container's Dockerfile to specify the ENTRYPOINT:

ENTRYPOINT ["ssm-entrypoint"]
CMD ["your-executable", "arg1", "arg2", "...argN"]

The SSM Entrypoint requires two environment variables to be set when running the container:

  • AWS_REGION: specifies the AWS region storing the SSM parameters used for this application
  • SSM_KEY_PATH: path-notated prefix for all keys that the entrypoint should fetch, e.g. /stage/myApp

Both of these environment variables are provided automatically for applications running on the Docker-based AWS Deployment Pipeline, such as used by CentralDispatch.

When using docker-compose locally, the entrypoint gem will do nothing, since proper AWS IAM credentials are required to fetch configuration. Use the docker-compose.yml, docker-compose.override.yml, or other mechanism, to provide environment variables locally.

In AWS, if the entrypoint script is unable to fetch configuration, the application will fail to start. This is by design to prevent the application from starting in an unexpected or unpredictable state.

Gem Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/cai-ecs-entrypoint.