bitovi/github-actions-deploy-docker-to-ec2 deploys any Docker-based app to an AWS VM (EC2) using Docker and Docker Compose.

The action will copy this repo to the VM and then run docker compose up.

⚠️ Migrating from v0.5.8 to v1.0.0 is not possible. Some resources keep the same ID and errors will appear.

This action will create an EC2 instance and the resources defined, copy this repo to the VM, install docker (and other options if enabled) and then run docker compose up.

If you would like to deploy a backend app/service, check out our other actions:

And more!, check our list of actions in the GitHub marketplace

This project is supported by Bitovi, a DevOps Consultancy and a proud supporter of Open Source software.

You can get help or ask questions on our Discord channel! Come hang out with us!

Or, you can hire us for training, consulting, or development. Set up a free consultation.

A lot! The whole code supporting this action migrated into a bigger repo, with more modules and functions. We concentrated our work there, hence any improvement done there benefits all of our actions.

Actions you said? Yes… go check our list of actions in the GitHub marketplace

New stuff! To name a few, cloudwatch for docker, VPC handling, EC2/ELB/APP port list, user_data for pre-ansible run, RDS (as Aurora replacement) among others. Check the v1-changes doc.

Adding new features and functionalities while keeping code consistent required a huge refactoring. Resources and objects got moved and renamed, making migration a really complicated path.
For that reason we recommend a clean start.
Version v0.5.8 will be the last of the v0 series, and new features will be added to v1 from now on.

1. Files for Docker
2. An AWS account

Your app needs a Dockerfile and a docker-compose.yaml file.

For more details on setting up Docker and Docker Compose, check out Bitovi's Academy Course: Learn Docker

You'll need Access Keys from an AWS account

We accept multiple ways to add environment variables. All of them will be merged into a .env file in the EC2 instance in a KEY=VALUE format. For secrects stored in AWS Secrets Manager we expect them to be in a JSON format, like '{"key":"value"}'. The rest could be in a KEY=VALUE format.

• env_aws_secret - Comma separated list of secret name(s) stored in AWS Secrets Manager
• env_repo - A file in your repo that contains env vars. As a default, we'll try to read repo_env, but you can change that to any other filename. (Including path)`
• env_ghv - An entry in Github actions variables
• env_ghs - An entry in Github secrets

version: '3.9'
services:
  app:
    env_file: .env

These environment variables are merged to the .env file quoted in the following order:

• Terraform passed env vars ( This is not optional nor customizable )
• Repository checked-in env vars - repo_env file as default. (KEY=VALUE style)
• Github Vars - Create a variable in your GH Repo - (KEY=VALUE style)
• Github Secret - Create a secret in your GH Repo - (KEY=VALUE style)
• AWS Secret - Comma separated list of JSON style like '{"key":"value"}' secrets.

Create .github/workflows/deploy.yaml with the following to build on push.

name: Basic deploy
on:
  push:
    branches: [ main ]

jobs:
  EC2-Deploy:
    runs-on: ubuntu-latest
    steps:
      - id: deploy
        uses: bitovi/[email protected]
        with:
          aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws_default_region: us-east-1

          aws_elb_app_port: 8080 # This should match the docker exposed port. Defaults to 3000.

name: Advanced deploy
on:
  push:
    branches: [ main ]

permissions:
  contents: read

jobs:
  EC2-Deploy:
    runs-on: ubuntu-latest
    environment:
      name: "EC2"
      url: ${{ steps.deploy.outputs.vm_url }}
    steps:
    - id: deploy
      name: Deploy
      uses: bitovi/[email protected]
      with:
        aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws_session_token: ${{ secrets.AWS_SESSION_TOKEN }}
        aws_default_region: us-east-1
        #aws_additional_tags: '{\"key\":\"value\",\"key2\":\"value2\"}'

        aws_r53_enable: true
        aws_r53_domain_name: bitovi.com
        aws_r53_sub_domain_name: app
        aws_r53_create_sub_cert: true

        ansible_start_docker_timeout: 600

        env_ghs: ${{ secrets.DOT_ENV }}
        env_ghv: ${{ vars.VARS }}
        env_aws_secret: some-secret,some-other
        aws_elb_app_port: 3000,8080
        aws_elb_listen_port: 443,8080
        aws_elb_healthcheck: "HTTP:8080"
        
        docker_cloudwatch_enable: true
        docker_cloudwatch_retention_days: 7

        aws_rds_db_enable: true

❇️ We use aws_resource_identifier as a unique ID throughout the code to name resources.
Keep this in mind if using any of our actions in different steps of the same job!
This ID is defined with the following default value: ${GITHUB_ORG_NAME}-${GITHUB_REPO_NAME}-${GITHUB_BRANCH_NAME}

1. AWS Specific
2. GitHub Commons main inputs
3. Secrets and Environment Variables
4. EC2
5. VPC
6. AWS Route53 Domains and Certificates
7. Load Balancer
8. Docker
9. EFS
10. RDS
11. DB Proxy
12. GitHub Deployment repo inputs

1. Action Outputs

The following inputs can be used as step.with keys

Most resources will contain the tag ${GITHUB_ORG_NAME}-${GITHUB_REPO_NAME}-${GITHUB_BRANCH_NAME}, some of them, even the resource name after. We limit this to a 60 characters string because some AWS resources have a length limit and short it if needed.

We use the kubernetes style for this. For example, kubernetes -> k(# of characters)s -> k8s. And so you might see some compressions are made.

For some specific resources, we have a 32 characters limit. If the identifier length exceeds this number after compression, we remove the middle part and replace it for a hash made up from the string itself.

Buckets names can be made of up to 63 characters. If the length allows us to add -tf-state, we will do so. If not, a simple -tf will be added.

As a default, the application will be deployed and the ELB public URL will be displayed.

If aws_r53_enable and aws_r53_enable_cert are true, we will look up for a certificate with the name of the domain defined in aws_r53_domain_name. (eg. example.com). We expect that certificate to contain both example.com and *.example.com in the defined region.

Setting aws_r53_create_root_cert to true will create this certificate with both example.com and *.example.com for you, and validate them. (DNS validation).

Setting aws_r53_create_sub_cert to true will create a certificate just for the subdomain, and validate it.

⚠️ Be very careful here! Created certificates are fully managed by Terraform. Therefor they will be destroyed upon stack destruction.

To change a certificate (root_cert, sub_cert, ARN or pre-existing root cert), you must first toogle aws_r53_enable_cert to false, run the action, and then set the aws_r53_enable_cert flag to true, add the desired settings and excecute the action again. (This will destroy the first certificate.)

This is necessary due to a limitation that prevents certificates from being changed while in use by certain resources.

Users looking to add non-ephemeral storage to their created EC2 instance have the following options; create a new efs as a part of the ec2 deployment stack, or mounting an existing EFS.

Option 1, you have access to the aws_efs_create attribute which will create a EFS resource and mount it to the EC2 instance in the application directory at the path: "app_root/data".

⚠️ Be very careful here! The EFS is fully managed by Terraform. Therefor it will be destroyed upon stack destruction.

Option 2, you have access to the aws_efs_fs_id attributes, which will mount an existing EFS Volume. If the volume have mount targets already created, set aws_efs_create_mount_target to false.

If you set aws_efs_create_mount_target and aws_efs_create_ha, mount targets will be created for all of the availability zones of the region.

If aws_rds_db_enable is set to true, this action will deploy a Postgres RDS database. Connection details will be present in the docker .env file. and a secret in AWS Secrets manager will be created.

⚠️ Database will be created and destroyed with the action. If you wish to use it in a separated repo, you can use our specific RDS action and add the secret as input here.

The following environment variables are added to the .env file in your app's docker-compose.yaml file.

To take advantage of these environment variables, be sure your docker-compose file is referencing the .env file like this:

version: '3.9'
services:
  app:
    # ...
    env_file: .env
    # ...

The available environment variables are:

The AWS root certificate is downloaded and accessible via the rds-combined-ca-bundle.pem file in root of your app repo/directory.

Example JavaScript to make a request to the Postgres cluster:

const { Client } = require('pg')

// set up client
const client = new Client({
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  ssl: {
    ca: fs.readFileSync('rds-combined-ca-bundle.pem').toString()
  }
});

// connect and query
client.connect()
const result = await client.query('SELECT NOW()');
await client.end();

console.log(`Hello SQL timestamp: ${result.rows[0].now}`);

BitOps allows you to define Infrastructure-as-Code for multiple tools in a central place. This action uses a BitOps Operations Repository to set up the necessary Terraform and Ansible to create infrastructure and deploy to it.

We would love for you to contribute to bitovi/github-actions-deploy-docker-to-ec2. Would you like to see additional features? Create an issue or a Pull Requests. We love discussing solutions!

The scripts and documentation in this project are released under the MIT License.