GitHub action to deploy 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.

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.

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

For envirnoment variables in your app, you can provide:

• repo_env - A file in your repo that contains env vars
• ghv_env - An entry in Github actions variables
• dot_env - An entry in Github secrets
• aws_secret_env - The path to a JSON format secret in AWS

Then hook it up in your docker-compose.yaml file like:

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 Secret - Create a secret named DOT_ENV - (KEY=VALUE style)
• AWS Secret - JSON style like '{"key":"value"}'

Create .github/workflow/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/github-actions-deploy-docker-to-ec2@v0.5.0
        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
          dot_env: ${{ secrets.DOT_ENV }}

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

permissions:
  contents: read

jobs:
  EC2-Deploy:
    runs-on: ubuntu-latest
    environment:
      name: ${{ github.ref_name }}
      url: ${{ steps.deploy.outputs.vm_url }}
    steps:
    - id: deploy
      name: Deploy
      uses: bitovi/github-actions-deploy-docker-to-ec2@v0.5.0
      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
        domain_name: bitovi.com
        sub_domain: app
        tf_state_bucket: my-terraform-state-bucket
        dot_env: ${{ secrets.DOT_ENV }}
        ghv_env: ${{ vars.VARS }}
        app_port: 3000
        additional_tags: "{\"key1\": \"value1\",\"key2\": \"value2\"}"

1. Action Defaults
2. Secrets and Environment Variables
3. EC2
4. EFS
5. RDS
6. Certificates
7. Load Balancer
8. Application
9. Terraform

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 domain_name is defined, we will look up for a certificate with the name of that domain (eg. example.com). We expect that certificate to contain both example.com and *.example.com.

If you wish to set up domain_name and disable the certificate lookup, set up no_cert to true.

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

Setting 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 set the no_cert flag to true, run the action, then set the no_cert flag to false, 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 create_efs 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 mount_efs attributes. Requiring an existing EFS id and optionally a primary security group id the existing EFS will be attached to the ec2 security group to allow traffic.

An example EFS Zone mapping;

{
  "a": {
    "subnet_id": "subnet-foo123",
    "security_groups: ["sg-foo123", "sg-bar456"]
  }
}

If aws_enable_postgres is set to true, this action will deploy an RDS cluster for Postgres.

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.PGHOST,
  port: process.env.PGPORT,
  user: process.env.PG_USER,
  password: process.env.PG_PASSWORD,
  database: process.env.PGDATABASE,
  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}`);

Specifically, the following resources will be created:

• AWS Security Group
  • AWS Security Group Rule - Allows access to the cluster's db port: 5432
• AWS RDS Aurora Postgres
  • Includes a single database (set by the input: aws_postgres_database_name. defaults to root)

Additional details about the cluster that's created:

• Automated backups (7 Days)
  • Backup window 2-3 UTC (GMT)
• Encrypted Storage
• Monitoring enabled
• Sends logs to AWS Cloudwatch

For more details, see operations/deployment/terraform/postgres.tf

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.