A PaaS built on top of Amazon EC2 Container Service (ECS)
Go Ruby Other
Permalink
Failed to load latest commit information.
.circleci Build with Go 1.7.6 Sep 19, 2017
bin Minor tweaks to bin/bootstrap Dec 9, 2016
cmd Trim version prefix May 28, 2018
contrib/amazon-ecs-agent Uses the ECS RunTask API to run attached processes. Mar 14, 2017
dbtest Allow tests to be run with docker-compose May 31, 2017
docs Set the default scheduler to cloudformation (#1118) Dec 14, 2017
empiretest Renames ProcfileExtractor to ImageRegistry Sep 7, 2017
events Add Stdout event stream Jun 13, 2016
internal Implements security enhancements on top of the realip package. Oct 4, 2017
logs Make uuid package an internal dependency Jul 28, 2017
pkg Add ability to view env for a past release May 28, 2018
procfile Update docs for scheduled processes (#1115) Nov 14, 2017
registry Fix pull by digest in Docker scheduling backend Oct 13, 2017
scheduler Fix pull by digest in Docker scheduling backend Oct 13, 2017
server Add ability to view env for a past release May 28, 2018
stats Track CloudFormation template sizes. Jul 27, 2016
tests Add a test May 28, 2018
twelvefactor Separate stdout/stderr streams for one-off commands. Aug 10, 2017
vendor Update cli package to latest version Nov 21, 2017
.bumpversion.cfg Bump version: 0.12.0 → 0.13.0 Sep 19, 2017
.dockerignore Adds support for ECS placement constraints and strategies. Aug 10, 2017
.gitignore Added supported container environment variables into docs Aug 1, 2017
CHANGELOG.md Merge branch 'stable-0.13' Apr 18, 2018
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Jun 13, 2017
CONTRIBUTING.md Document package structure Aug 9, 2017
Dockerfile Bump version: 0.12.0 → 0.13.0 Sep 19, 2017
Dockerfile.test Build with Go 1.7.6 Sep 19, 2017
LICENSE Add BSD license. Fixes GH-193 Mar 24, 2015
Makefile Make TYPE overrideable Sep 19, 2017
README.md Simplifies the readme slightly Aug 10, 2017
VERSION Bump version: 0.12.0 → 0.13.0 Sep 19, 2017
apps.go Remove dependency on github.com/remind101/pkg/timex Jul 28, 2017
apps_test.go Move from empire/empire to empire. Jul 1, 2015
certs.go Application maintenance mode Jun 9, 2017
configs.go Only wrap the release creation in a transaction Jul 12, 2016
configs_test.go Store user and commit message with release description May 10, 2016
constraints.go more comments. Jun 24, 2016
constraints_test.go Remove 1024 limit on cpu shares (#1124) Apr 17, 2018
db.go Adds flags for configuring instance port pool. Aug 1, 2017
db_test.go Private scope. Jun 24, 2016
deployments.go Renames ProcfileExtractor to ImageRegistry Sep 7, 2017
doc.go Some small tweaks. Jun 24, 2016
docker-compose.test.yml Allow tests to be run with docker-compose May 31, 2017
docker-compose.yml Allow tests to be run with docker-compose May 31, 2017
domains.go Remove dependency on github.com/remind101/pkg/timex Jul 28, 2017
domains_test.go Move from empire/empire to empire. Jul 1, 2015
empire.go Renames ProcfileExtractor to ImageRegistry Sep 7, 2017
empire.png Prettier readme. Jan 14, 2016
empire_test.go Allow tests to be run with docker-compose May 31, 2017
events.go Fixes a panic in MultiEventStream Aug 31, 2017
events_test.go Fixes a panic in MultiEventStream Aug 31, 2017
logs.go Move logs implementations to package Jul 28, 2017
migrations.go Adds flags for configuring instance port pool. Aug 1, 2017
migrations_test.go Adds flags for configuring instance port pool. Aug 1, 2017
mkdocs.yml Removes documentation on known limitations. Aug 9, 2017
processes.go Adds support for ECS placement constraints and strategies. Aug 10, 2017
processes_test.go more comments. Jun 24, 2016
registry.go Renames ProcfileExtractor to ImageRegistry Sep 7, 2017
releases.go Adds support for ECS placement constraints and strategies. Aug 10, 2017
releases_test.go Merge default Range. Jul 24, 2015
runner.go Separate stdout/stderr streams for one-off commands. Aug 10, 2017
scheduler.go Separate stdout/stderr streams for one-off commands. Aug 10, 2017
slugs.go Renames ProcfileExtractor to ImageRegistry Sep 7, 2017
tasks.go Automated refactoring https://gist.github.com/ejholmes/a0c7a4656c4aab… Mar 29, 2017
users.go More docs. Jun 24, 2016
version.go Bump version: 0.12.0 → 0.13.0 Sep 19, 2017

README.md

Empire

readthedocs badge Circle CI Slack Status

Empire

Empire is a control layer on top of Amazon EC2 Container Service (ECS) that provides a Heroku like workflow. It conforms to a subset of the Heroku Platform API, which means you can use the same tools and processes that you use with Heroku, but with all the power of EC2 and Docker.

Empire is targeted at small to medium sized startups that are running a large number of microservices and need more flexibility than what Heroku provides. You can read the original blog post about why we built empire on the Remind engineering blog.

Quickstart

Install

To use Empire, you'll need to have an ECS cluster running. See the quickstart guide for more information.

Architecture

Empire aims to make it trivially easy to deploy a container based microservices architecture, without all of the complexities of managing systems like Mesos or Kubernetes. ECS takes care of much of that work, but Empire attempts to enhance the interface to ECS for deploying and maintaining applications, allowing you to deploy Docker images as easily as:

$ emp deploy remind101/acme-inc:master

Heroku API compatibility

Empire supports a subset of the Heroku Platform API, which means any tool that uses the Heroku API can probably be used with Empire, if the endpoint is supported.

As an example, you can use the hk CLI with Empire like this:

$ HEROKU_API_URL=<empire_url> hk ...

However, the best user experience will be by using the emp command, which is a fork of hk with Empire specific features.

Routing

Empire's routing layer is backed by internal ELBs. Any application that specifies a web process will get an internal ELB attached to its associated ECS Service. When a new version of the app is deployed, ECS manages spinning up the new versions of the process, waiting for old connections to drain, then killing the old release.

When a new internal ELB is created, an associated CNAME record will be created in Route53 under the internal TLD, which means you can use DNS for service discovery. If we deploy an app named feed then it will be available at http://feed within the ECS cluster.

Apps default to only being exposed internally, unless you add a custom domain to them. Adding a custom domain will create a new external ELB for the ECS service.

Deploying

Any tagged Docker image can be deployed to Empire as an app. Empire doesn't enforce how you tag your Docker images, but we recommend tagging the image with the git sha that it was built from (any any immutable identifier), and deploying that.

When you deploy a Docker image to Empire, it will extract a Procfile from the WORKDIR. Like Heroku, you can specify different process types that compose your service (e.g. web and worker), and scale them individually. Each process type in the Procfile maps directly to an ECS Service.

Contributing

Pull requests are more than welcome! For help with setting up a development environment, see CONTRIBUTING.md

Community

We have a google group, empire-dev, where you can ask questions and engage with the Empire community.

You can also join our Slack team for discussions and support.