DEV Community: Andreas Wittig

Antivirus for File Uploads: Add Virus and Malware Scan to Any App

Andreas Wittig — Thu, 26 Feb 2026 19:13:02 +0000

As a developer, you are aware of the fact that all user input needs to be validated carefully. But, how do you ensure users and 3rd parties are not uploading files infected by viruses, trojans, ransomware, or other kinds of malware? You don't? Let me show you how to add virus and malware scanning to any app with ease.

Why?

Distribution Risk: Your app shouldn't be a "Patient Zero" for spreading malware to others.
Lateral Movement: Once a malicious file is on your server, it can be used to attack your infrastructure.
The Compliance "Must-Have": If you’re dealing with PCI DSS, ISO 27001, HIPAA, or SOC 2, malware scanning isn't just a good idea—it’s often a requirement.

Virus and Malware Scan API

Modern virus and malware scanning is just an API call away.

User or 3rd party sends file to your app.
App calls the Virus and Malware Scan API.
Virus and Malware Scan API scans the file and returns the scan result.
Depending on the scan result, app proceeds with quarantining/deleting or processing the file.

In the following, I will demonstrate how to use the Virus and Malware Scan API by attachmentAV.

An API key and subscription is required to access the Virus and Malware Scan API by attachmentAV. Learn more.

Scan a file with Virus and Malware Scan API

The following snippet shows how to scan a file by calling the API with curl. Replace <API_KEY_PLACEHOLDER> with your API key and @path/to/file with the path to the file that you want to scan.

curl \
  -X POST \
  -H 'x-api-key: <API_KEY_PLACEHOLDER>' \
  -H 'Content-Type: application/octet-stream' \
  -d '@path/to/file' \
  https://eu.developer.attachmentav.com/v1/scan/sync/binary

The API responds with the following result, for example.

{"status":"clean","size":73928372,"realfiletype":"Adobe Portable Document Format (PDF)"}

Implementing virus scanning with Java

Use the Java SDK virus-scan-sdk to integrate attachmentAV with your Java application.

The SDK is available in the Maven Central repository.

<dependency>
  <groupId>com.attachmentav</groupId>
  <artifactId>virus-scan-sdk</artifactId>
  <version>0.6.0</version>
</dependency>

The following snippet illustrates how to send a file to the Virus and Malware Scan API. Don't forget to replace <API_KEY_PLACEHOLDER> with the API belonging to your subscription. Also replace /path/to/file with the path to the file you want to scan.

import com.attachmentav.api.AttachmentAvApi;
import com.attachmentav.client.ApiClient;
import com.attachmentav.client.ApiException;
import com.attachmentav.client.Configuration;
import com.attachmentav.model.ScanResult;
import java.io.File;

// ...

ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("<API_KEY_PLACEHOLDER>");
AttachmentAvApi api = new AttachmentAvApi();
ScanResult result = api.scanSyncBinaryPost(new File("/path/to/file"));
System.out.println("Scan Result: " + result.getStatus());

Adding malware protection to JavaScript or TypeScript app

Java isn't for you, but you are all-in on TypeScript or JavaScript? Here you go. There's an SDK for TS/JS as well.

npm i @attachmentav/virus-scan-sdk-ts

Find an example on how to send a file to the Virus and Malware Scan API in the following. Don't forget to replace <API_KEY_PLACEHOLDER> with the API belonging to your subscription. Also replace /path/to/file with the path to the file you want to scan.

import { AttachmentAVApi, Configuration } from '@attachmentav/virus-scan-sdk-ts';
import { readFileSync } from 'node:fs';
import { Blob } from 'node:buffer';

const config = new Configuration({
  apiKey: '<API_KEY_PLACEHOLDER>'
});

const api = new AttachmentAVApi(config);

const scanResult = await api.scanSyncBinaryPost({
  body: new Blob([readFileSync('/path/to/file')])
});
console.log('Sync binary scan result:', scanResult);

Check files for viruses and malware with Python

Neither, Java nor JS/TS are for you. Here is my last example for all Python developers out there.

The following listing explains how to scan a file for virus and malware by using the attachmentAV SDK.

First, install the package.

pip install attachmentav-virus-malware-scan-sdk

Next, add the following lines to your Python code. Don't forget to replace <API_KEY_PLACEHOLDER> with the API belonging to your subscription. Also replace /path/to/file with the path to the file you want to scan.

import attachmentav

configuration = attachmentav.Configuration()
configuration.api_key['apiKeyAuth'] = "<API_KEY_PLACEHOLDER>"

with attachmentav.ApiClient(configuration) as api_client:
  api_instance = attachmentav.AttachmentAVApi(api_client)

with open("/path/to/file", "rb") as file:
    file_content = file.read()
    scan_result = api_instance.scan_sync_binary_post(file_content)
    print(scan_result)

Wrapping Up: Better Safe Than Sorry

Securing file uploads should neither be a secondary thought nor a massive infrastructure headache. Whether you are building a small MVP or scaling an enterprise platform, the Virus and Malware Scan API by attachmentAV bridges the gap between "hoping for the best" and actually being protected.

Add virus and malware protection to your app today! Get started with attachmentAV's Virus and Malware Scan API.

Connect to your EC2 instance using SSH the modern way

Andreas Wittig — Wed, 02 Feb 2022 11:26:42 +0000

Did you know that establishing an SSH connection with an EC2 instance is possible without configuring a key pair and allowing inbound traffic on port 22? How is that possible? The secret is a combination of EC2 Instance Connect and Systems Manager (SSM). When following this article, connecting with an EC2 instance is as simple as typing ssh i-059499e6abc8fbe6b into your terminal.

First of all, the following video demonstrates how to establish an SSH connection with an EC2 instance by using EC2 Instance Connect and Systems Manager.

The following diagram explains the approach in more detail.

The user sends her public key to EC2 Instance Connect using the AWS CLI.
EC2 Instance connect pushes the key to the EC2 instance. The key remains for 60 seconds.
An SSM agent running on the EC2 instance establishes a bidirectional channel with the SSM backend.
The user establishes an SSH connection through a Websocket between Terminal and SSM.
Authentication and authorization for the user and the SSM agent is IAM's job.

How do you make this approach happen on your local machine and EC2 instances?

Make sure the SSM agent is running on your EC2 instances - which is already the case for Amazon Linux and Amazon Linux 2.
Double check that the SSM agent running on your machines can connect with the SSM API through an internet gateway, NAT gateway, or VPC endpoint.
Attach an IAM role - granting the SSM agent access to the SSM API - to each EC2 instance to
Install the AWS CLI and the session manager plugin on your local machine.
Configure your SSH client to use EC2 Instance Connect and Systems Manager to establish a tunnel for SSH connections.

Are you confused about the different options to connect by using EC2 Instance Connect and Systems Manager? Check out Petri's comparision: EC2 Instance Connect vs. SSM Session Manager

IAM role required by SSM agent

As mentioned before, the SSM agent is running on most EC2 instances already. That's because the agent is bundled into Amazon Linux, Amazon Linux 2, SUSE Linux Enterprise Server (12 and 15), and Ubuntu Server (16.04, 18.04, and 20.04) by default.

Learn how to Manually install SSM Agent on EC2 instances for Linux from the AWS documentation.

However, the SSM agent requires an IAM role attached to the EC2 instance granting access to the SSM API. That's not a default, so you probably need to create a new IAM role or add a policy to existing roles.

You can either use the predefined policy AmazonSSMManagedInstanceCore (arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore) managed by AWS. Or create your own managed or in-line policy with the following contents.

{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Action": [
 "ssmmessages:*",
 "ec2messages:*",
 "ssm:UpdateInstanceInformation"
 ],
 "Resource": "*"
 }
 ]
}

Install the AWS CLI and session manager plugin

You will use the AWS Command Line Interface (CLI) to push your public key via EC2 Instance Connect and establish a tunnel for your SSH connection with the EC2 instance.

Therefore, make sure to install the AWS CLI on your local machine. Besides that, you need to install the session manager plugin.

I prefer brew to install the AWS CLI and the session manager plugin on macOS.

brew install awscli session-manager-plugin

Configuring your SSH client

Next, you need to configure your SSH client. To do so, edit the ~/.ssh/config file on your local machine. Please add the following snippet configuring connections for all hosts, starting with i- at the end of the file. Do not forget to replace $PRIVATE_KEY and $PUBLIC_KEY with the path to your private and public key.

# SSH over Session Manager
host i-*
 IdentityFile $PRIVATE_KEY
 User ec2-user
 ProxyCommand sh -c "aws ec2-instance-connect send-ssh-public-key --instance-id %h --instance-os-user %r --ssh-public-key 'file://$PUBLIC_KEY' --availability-zone '$(aws ec2 describe-instances --instance-ids %h --query 'Reservations[0].Instances[0].Placement.AvailabilityZone' --output text)' && aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

For me, the snippet looks as follows.

# SSH over Session Manager
host i-*
 IdentityFile ~/.ssh/id_ed25519
 User ec2-user
 ProxyCommand sh -c "aws ec2-instance-connect send-ssh-public-key --instance-id %h --instance-os-user %r --ssh-public-key 'file://~/.ssh/id_ed25519.pub' --availability-zone '$(aws ec2 describe-instances --instance-ids %h --query 'Reservations[0].Instances[0].Placement.AvailabilityZone' --output text)' && aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

The ProxyCommand contains a one-liner that I'd like to explain in more detail.

First, we need to find out the availability zone the instance is running in. The command aws ec2 describe-instances returns the necessary information. Please note that %h will be replaced with the host, for example, i-059499e6abc8fbe6b.

aws ec2 describe-instances --instance-ids %h --query 'Reservations[0].Instances[0].Placement.AvailabilityZone' --output text

Next, you need to push your public key to the EC2 instance. That's why you need to execute the aws ssm start-session command.

aws ec2-instance-connect send-ssh-public-key --instance-id %h --instance-os-user %r --ssh-public-key 'file://~/.ssh/id_ed25519.pub' --availability-zone '$(...)'

Last but not least, you need to establish the SSH session through a WebSocket connection. That's the job of the aws ssm start-session command.

aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'

Connect to your EC2 instance using SSH

You are ready to connect with your EC2 instance using SSH. All you need to do is type ssh followed by an EC2 instance ID into your terminal.

ssh i-059499e6abc8fbe6b

By the way, you can even copy files with scp.

ssh example.txt i-059499e6abc8fbe6b:/tmp/

That's it. I hope you enjoy this approach to connect to your EC2 instances using SSH as much as I do.

Did you run into any issues while following my instructions? Do you love the approach to connect with your EC2 instances? Please let me know!

AWS Cost Optimization 101

Andreas Wittig — Mon, 13 Jan 2020 15:01:24 +0000

The beginning of the year is the perfect time to clean up and optimize. This also applies to your AWS bill. I've composed practical tips on how to cut costs with small effort.

The good thing about AWS: you typically pay per usage. The bad thing about AWS: understanding the pricing models of all the AWS services is hard. Little self-promotion: our consulting firm widdix offers analyzing and optimizing your AWS bill.

The following mind map provides guidance for reducing costs based on my experience from analyzing and reducing AWS bills for various clients. Download the mind map as a PDF file for better readability.

Let me start with the process of analyzing your AWS bill.

Use the Cost Explorer to aggregate costs by service.
1. Which services cause the highest costs?
2. Do the costs per service match with your assumptions? For example, it is quite unlikely that you want to spend 2x more on CloudWatch than on EC2.
Visualize your spending among the last 12 months.
1. Are costs increasing by a similar amount each month for a specific service? If so, you might be piling up unused resources (e.g., EBS snapshots).
2. Any high cost increases not caused by changes to your cloud infrastructure?
3. Does the cost increase per month match with your revenue numbers?
Open your AWS bill for the last three months and drill down into the details.
1. Which resources of a service cause high costs? Justify the costs.
2. Do the costs per service match with your estimations?
3. Are there any hints for expenses caused by unused resources?

Primarily, you should watch out for the following aspects.

EC2

Purchase Savings Plans for baseline capacity. The deal is simple: you commit to a monthly usage of computing capacity, AWS grants a discount on the on-demand price. Read Reduce your AWS bill with Savings Plans
to learn more.

Identify and terminate unused instances. Boring but very efficient.

Verify that instance type still reflects the current workload. Check the CloudWatch metrics for CPU, Storage I/O, and networking to come up with a first guess. After that, experiment to test your assumption.

Verify that the maximum I/O performance of the instance matches the performance of your EBS volumes. Remember that there is a network between your EC2 instance and your EBS volume. The instance type limits the maximum throughput to all attached EBS volumes. Make sure that matches with the configuration of your EBS volumes, where the volume type and provisioned IOPS define the maximum throughput. See EBS Volume Types
and EBS–Optimized Instances for more details.

Use Spot Instances for stateless and non-production workloads. Keep in mind that AWS might terminate your spot instance anytime before using them in production. Read 3 simple ways of saving up to 90% of EC2 costs to learn more.

Switching to the latest instance types often cuts costs. For example, migrating from m4.large to m5.large? reduces the costs by 4%. On top of that, you get a small performance improvement as well.

Using AMD- or ARM-based instance types in favor of Intel-based instance types is also worth a look.

Savings potential for AMD-based instance types (e.g., t3a, m5a, and r5a): 10%
Savings potential for ARM-based instance types: 40%

On the one hand, it is a little bit more work to migrate to an Open Source operating system. Our operating system of choice on AWS is Amazon Linux, a free of charge Linux image maintained by Amazon. On the other hand, the cost savings are enormous.

EBS

Commonly, EBS snapshots are piling up. Therefore, delete snapshots created to backup data that are no longer needed. Also, check whether your backup solution deletes old snapshots. Have you written a backup solution with Lambda? Replace it with AWS Backup. Read Review: AWS Backup - A centralized place for managing backups? to learn more.

Delete snapshots belonging to unused AMIs. A typical waste management problem when your deployment pipeline builds AMIs for every commit.

Search for unused volumes and delete them. Check whether someone (script, Kubernetes, ...) creates volumes automatically and does not clean them up.

S3

It's obvious but still valid: delete unnecessary objects and buckets.

Consider using S3 Intelligent Tiering. Or, if you need to archive data, check out Glacier Deep Archive. Read 6 new ways to reduce your AWS bill with little effort to learn more.

Configure life-cycle policies define a retention period for objects. Read Object Lifecycle Management to learn more.

VPC

Check costs for NAT gateways. I've seen scenarios where placing EC2 instances into a public subnet was the only option to avoid horrendous traffic costs.

Also, create VPC endpoints for S3 and DynamoDB. Doing so reduces the traffic processed by your NAT gateways.

Traffic within the VPC is free? No, it is not. Traffic between Availability Zones is charged at $0.02/GB. Check the traffic costs and think about making changes to your architecture when necessary.

A VPC endpoint costs $7.20 per AZ and month in US East (N. Virginia). Adding VPC endpoints for ten services in 3 AZs costs $216 per month. And the processed data is not even included. In general, avoid VPC endpoints when possible. Read 6 new ways to reduce your AWS bill with little effort to learn more.

CloudWatch

Configure a retention period for all log groups. For example, delete log messages after 30 days.

Check costs for metrics API calls caused by 3rd party tools (e.g., Prometheus, Datadog, ...). Make sure you are only polling metrics that you need and set the polling interval to 5 minutes.

Each CloudWatch alarms cost $0.10 per month; a CloudWatch dashboard costs $3.00 per month. Therefore, delete needless alarms and dashboards.

Identify unnecessary custom metrics. For example, configure the CloudWatch Agent only to send metrics that you need for monitoring.

Check costs for log ingestion. It might be necessary to reduce or filter the log events that you send to CloudWatch.

Serverless

Optimize memory configuration for Lambda functions. Check out AWS Lambda Power Tuning.

Use Provisioned Concurrency to reduce costs for high traffic Lambda functions and evaluate HTTP APIs as an alternative to API Gateway. Read All you need to know about AWS re:Invent in 2019 to learn more.

ECS

Using Fargate allows you to get rid of an overprovisioned fleet of EC2 instances. If using Fargate is not an option, check out the ECS Capacity Provider to scale the fleet of EC2 instances easily. Read ECS vs. Fargate: What's the difference? to learn more.

Purchase Savings Plans for Fargate. Read Reduce your AWS bill with Savings Plans to learn more.

Use Fargate Spot for non-production workloads. Read AWS Fargate Spot Now Generally Available to learn more.

RDS

Enable RDS Storage Auto Scaling instead of over-provisioning storage capacity.

Consider switching to Aurora Serverless for unsteady. Check out our review to learn about the pros and cons.

And don't forget to verify that the instance type of your database still reflects the current workload. Also, check that the maximum I/O performance of the compute layer matches the storage layer.

License costs for traditional database systems are tremendous. Migrating to an Open Source database should be on your long or short term TODO list.

DynamoDB

Switch to On-demand capacity mode for unsteady workloads. Read Cost savings with DynamoDB On-Demand: Lessons learned to learn more.

If on-demand capacity is not for you, use auto-scaling to adjust the provisioned capacity to the workload.

Elasticsearch

Make use of Reserved Instances were planning one year is feasible.

Evaluate UltraWarm tier (Preview) to retain large amounts of data at lower costs. Read UltraWarm for Amazon Elasticsearch Service to learn more.

Route 53

Increase TTL for records to reduce queries.

Are you using Route 53 resolver endpoints? You typically pay $270 per month for endpoints in 3 AZs. Therefore, you might want to consolidate your resolver endpoints from multiple AWS accounts.

CloudFront

Check the hit/miss ratio of the cache and adjust your configuration and TTL accordingly.

Bypassing the CloudFront cache and loading assets directly from S3 is more expensive. Therefore, restrict access to S3 by using an Origin Access Identity.

CloudTrail

Simple: delete unnecessary trails. Keep in mind that configuring more than one trail results in additional costs.

Check costs for data events (S3 and Lambda). Read AWS CloudTrail: your audit log is incomplete
to learn more.

Now it is up to you. Go and reduce your AWS bill!

One more thing: make sure you have created a budget alarm to get notified about unexpected costs in advance. Consult the AWS documentation or learn how to receive AWS budget alarms via Slack.

Dockerizing Ruby on Rails

Andreas Wittig — Thu, 19 Dec 2019 15:59:45 +0000

Did you dockerize your Ruby on Rails application already? You definitely should! Read on to learn why and how.

Shipping software is a challenge. Endless installation instructions explain in detail how to install and configure an application as well as all its dependencies. But in practice, following installation instructions ends with frustration: the required version of Ruby is not available to install from the repository, the configuration file is located in another directory, the installation instructions do not cover the operating system you need or want to use, etc.

And it gets worse: to be able to scale on-demand and recover from failure, we need to automate the installation and configuration of our application and its runtime environment. Implementing the required automation with the wrong tools is very time-consuming and error-prone.

But what if you could bundle your application with all its dependencies and run it on any machine: your MacBook, your Windows PC, your test server, your on-premises server, and your cloud infrastructure? That's what Docker is all about.

In short: Docker is a toolkit to deliver software.

This blog post is an excerpt from our book Rapid Docker on AWS.

The most important part of the Docker toolkit is the container. A container is an isolated runtime environment preventing an application from accessing resources from other applications running on the same operating system. The concept of a jail - later called a container - had been around on UNIX systems for years. Docker uses the same ideas but makes them a lot easier to use.

With Docker containers, the differences between different platforms like your developer machine, your test system, and your production system are hidden under an abstraction layer. But how do you distribute your application with all its dependencies to multiple platforms? By creating a Docker image. A Docker image is similar to a virtual machine image, such as an Amazon Machine Image (AMI) that is used to launch an EC2 instance. The Docker image contains an operating system, the runtime environment, 3rd party libraries, and your application. The following figure illustrates how you can fetch an image and start a container on any platform.

But how do you create a Docker image for your web application? By creating a script that builds the image step by step: a so-called Dockerfile.

Next, you will learn how to dockerize a typical Ruby on Rails application.

The project structure of a typical Ruby on Rails project looks like this:

├── Gemfile
├── README.md
├── Rakefile
├── app
├── babel.config.js
├── bin
├── config
├── config.ru
├── db
├── lib
├── log
├── package.json
├── postcss.config.js
├── public
├── storage
├── test
├── tmp
├── vendor
└── yarn.lock

How to bundle an application with the described project structure? Let's have a look at the Dockerfile:

Based on Amazon Linux 2.
Installs Node.js, required by yarn, required by Ruby on Rails.
Installs Ruby and Ruby on Rails with all needed dependencies.
Installs wait-for-it - a helper to make sure that the MySQL database is up and running before the Ruby container is started with docker-compose.
Copies all files except the ignores defined in the file .dockerignore.
Installs all Ruby dependencies of the application and generates the static assets.
Configured a custom entry point that runs the database migrations when the container starts before the application is started.
Exposes port 3000 and defines the default command to run the application.

FROM amazonlinux:2.0.20190508

RUN mkdir /usr/src/app
WORKDIR /usr/src/app

# Install Node.js (needed for yarn)
RUN curl -sL https://rpm.nodesource.com/setup_10.x | bash -
RUN yum -y install nodejs gcc-c++ make

# Install Ruby & Rails
RUN curl -sL -o /etc/yum.repos.d/yarn.repo https://dl.yarnpkg.com/rpm/yarn.repo
RUN amazon-linux-extras enable ruby2.6 \
  && yum -y install git tar gzip yarn zlib-devel sqlite-devel mariadb-devel ruby-devel rubygems-devel rubygem-bundler rubygem-io-console rubygem-irb rubygem-json rubygem-minitest rubygem-net-http-persistent rubygem-net-telnet rubygem-power_assert rubygem-rake rubygem-test-unit rubygem-thor rubygem-xmlrpc \
  && gem install rails

# Install wait-for-it
COPY docker/wait-for-it.sh /usr/local/bin/
RUN chmod u+x /usr/local/bin/wait-for-it.sh

# Copy Ruby files (see .dockerignore)
COPY . .

# Install Ruby dependencies
ENV RAILS_ENV production
ENV RAILS_LOG_TO_STDOUT enabled
ENV RAILS_SERVE_STATIC_FILES enabled
RUN bin/bundle install --deployment --without development test
# see https://github.com/rails/rails/issues/32947 for SECRET_KEY_BASE workaround
RUN SECRET_KEY_BASE=dummy bin/rails assets:precompile

# Configure custom entrypoint to run migrations
COPY docker/custom-entrypoint /usr/local/bin/
RUN chmod u+x /usr/local/bin/custom-entrypoint
ENTRYPOINT ["custom-entrypoint"]

# Expose port 3000 and start Rails server
EXPOSE 3000
CMD ["bin/rails", "server", "--binding=0.0.0.0"]

To limit the amount of data that needs to be sent to Docker, the .dockeringore file defines an exclude list for files and directories that you typically do not need to include in the Docker image.

aws/*
log/*
storage/*
tmp/*
public/assets/*
public/packs/*

It is a best practice when dockerizing applications to use environment variables instead of configuration files. Do not use files to store the configuration for your application. Use environment variables instead. Luckily, Ruby on Rails comes with it's own configuration mechanism that supports environment variables out of the box. Check out the file config/database.rb to see how environment variables are used to configure the database connection.

# ...
production:
  <<: *default
  host: <%= ENV['DATABASE_HOST'] %>
  database: <%= ENV['DATABASE_NAME'] %>
  username: <%= ENV['DATABASE_USER'] %>
  password: <%= ENV['DATABASE_PASSWORD'] %>

One more thing: it is necessary to run the database migration each time you roll out a new version of your application. The easiest way to do so is to execute db:migrate each time you start the Docker container. To do so, the Dockerfile adds a so-called ENTRYPOINT which references the shell script custom-entrypoint. Each time you start the Docker container, the entry point script gets executed as well.

The custom-entrypoint script:

Waits until it is possible to establish a database connection.
Executes the database migration by calling db:migrate.
Starts the puma web server.

#!/bin/bash
set -e

if [ -n "${WAIT_FOR_IT}" ]; then
  wait-for-it.sh mysql:3306
fi

echo "running migrations"
bin/rails db:migrate

echo "starting $@"
exec "$@"

That's it! You are ready to build a Docker image bundling your Ruby on Rails application.

docker build -t myapp:latest .

Start a container based on the image ...

docker run -p 3000:3000 myapp:latest

... and open http://localhost:3000.

You have successfully dockerized your Ruby on Rails application. What is next?

Push the Docker image into a private registry (e.g., Amazon ECR).
Deploy your application in the cloud (e.g., with ECS and Fargate).

Want to learn more about how to deploy your application on AWS? Check out our new book and online seminar Rapid Docker on AWS. Production-ready infrastructure templates and deployment pipeline included.

How to dockerize your Node.js Express application for AWS Fargate?

Andreas Wittig — Mon, 09 Dec 2019 16:51:42 +0000

My first project with Node.js - an asynchronous event-driven JavaScript runtime, designed to build scalable network applications - was building an online trading platform in 2013. Since then, Node.js is one of my favorite technologies. I will show you how to dockerize your Node.js application based on Express - a fast, unopinionated, minimalist web framework - and run it on AWS Fargate in this blog bost. I like AWS Fargate because running containers in the cloud were never easier.

This blog post is an excerpt from our book Rapid Docker on AWS.

Read on to learn how to build a Docker image for a Node.js application.

Building the Docker image

The Dockerfile is based on the official Node.js Docker Image: node:10.16.2-stretch. Static files (folders img and css) are served by Express as well as the dynamic parts. The following details are required to understand the Dockerfile:

envsubst is used to generate the config file from environment variables
npm ci --only=production installs the dependencies declared in package.json (package-lock.json, to be more precise)
The Express application listens on port 8080
The Express application's entry point is server.js and can be started with node server.js

A simple server.js file follows. Yours likely is more complicated.

const express = require('express');

const app = express();
app.use('/css', express.static('css'));
app.use('/img', express.static('img'));

app.get('/health-check', (req, res, next) => {
  res.sendStatus(200);
});

app.listen(8080, '0.0.0.0');

Customization Most likely, your folder structure is different. Therefore, adapt the Copy config files and Copy Node.js files section in the following Dockerfile to your needs.

FROM node:10.16.2-stretch

WORKDIR /usr/src/app

ENV NODE_ENV production

# Install envsubst
RUN apt-get update && apt-get install -y gettext
COPY docker/custom-entrypoint /usr/local/bin/
RUN chmod u+x /usr/local/bin/custom-entrypoint
ENTRYPOINT ["custom-entrypoint"]
RUN mkdir /usr/src/app/config/

# Copy config files
COPY config/*.tmp /tmp/config/

# Install Node.js dependencies
COPY package*.json /usr/src/app/
RUN npm ci --only=production

# Copy Node.js files
COPY css /usr/src/app/css
COPY img /usr/src/app/img
COPY views /usr/src/app/views
COPY server.js /usr/src/app/

# Expose port 8080 and start Node.js server
EXPOSE 8080
CMD ["node", "server.js"]

The custom entrypoint is used to generate the config file from environment variables with envsubst.

#!/bin/bash
set -e

echo "generating configuration files"
FILES=/tmp/config/*
for f in $FILES
do
  c=$(basename $f .tmp)
  echo "... $c"
  envsubst < $f > /usr/src/app/config/${c}
done

echo "starting $@"
exec "$@"

Next, you will learn how to test your containers and application locally.

Testing locally

Use Docker Compose to run your application locally. The following docker-compose.yml file configures Docker Compose and starts two containers: Node.js and a MySQL database.

version: '3'
services:
  nodejs:
    build:
      context: '..'
      dockerfile: 'docker/Dockerfile'
    ports:
    - '8080:8080'
    depends_on:
    - mysql
    environment:
      DATABASE_HOST: mysql
      DATABASE_NAME: app
      DATABASE_USER: app
      DATABASE_PASSWORD: secret
  mysql:
    image: 'mysql:5.6'
    command: '--default-authentication-plugin=mysql_native_password'
    ports:
    - '3306:3306'
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: app
      MYSQL_USER: app
      MYSQL_PASSWORD: secret

The following command starts the application:

docker-compose -f docker/docker-compose.yml up --build

Magically, Docker Compose will spin up three containers: NGINX, Django, and MySQL. Point your browser to http://localhost:8080 to check that your web application is up and running. The log files of all containers will show up in your terminal, which simplifies debugging a lot.

After you have verified that your application is working correctly, cancel the running docker-compose process by pressing CTRL + C, and tear down the containers:

docker-compose -f docker/docker-compose.yml down

Deploying on AWS

You are now ready to deploy your application on AWS.

(1) Build Docker image:

docker build -t nodejs-express:latest -f docker/Dockerfile .

(2) Create ECR repository:

aws ecr create-repository --repository-name nodejs-express \
  --query 'repository.repositoryUri' --output text

(3) Login to Docker registry (ECR):

$(aws ecr get-login --no-include-email)

(4) Tag Docker image:

docker tag nodejs-express:latest \
111111111111.dkr.ecr.eu-west-1.amazonaws.com/\
nodejs-express:latest

(5) Push Docker image:

docker push \
111111111111.dkr.ecr.eu-west-1.amazonaws.com/\
nodejs-express:latest

There is only one step missing: you need to spin up the cloud infrastructure.

Use our Free Templates for AWS CloudFormation.
Use our cfn-modules.
Use the blueprint from our book Rapid Docker on AWS.

Checklist: Is your application ready for a container cluster?

Andreas Wittig — Thu, 28 Nov 2019 21:16:41 +0000

Is your application ready to run on a container cluster? Use this checklist to find out whether you are good to deploy your application on Amazon Elastic Container Service (ECS) and AWS Fargate or any other container cluster solution.

Does your application fulfill the following five requirements?

✅ Stateless: avoid persisting data

Your application (call it a microservice if you want to) is stateless. Answering a request or processing a job does not rely on reading data stored by previous requests or jobs. This applies to data from memory as well as a local disk.

Instead of that, your application stores data in a SQL/NoSQL database (e.g., RDS or DynamoDB), an in-memory database (Elasticache), or any other fully-managed storage service (e.g., S3).

✅ Logging: write to stdout and stderr

Your application writes log messages to standard output (stdout) and standard error (stderr). Do not write log messages to files. (see Stateless). Docker has built-in support to ship log messages from stdout and stderr to various centralized logging solutions (e.g., CloudWatch Logs). Check out A simple way to manage log messages from containers: CloudWatch Logs to learn more.

✅ Configuration: use environment variables

Your application reads configuration parameters from environment variables (e.g., the database endpoint or any other service endpoint). Do not use files to store the configuration for your application.

Use a templating engine for configuration files if you are containerizing a legacy application. I prefer envsubst to do so. Alternatively, you could have a look at Dockerizing legacy applications with confd.

✅ Process: restrict to one process

Your container starts exactly one main process. If your application consists of more than one process, split them up into multiple containers. For example, if you run NGINX and PHP-FPM, create two containers.

✅ Remote access: disable SSH

Your container does not start an SSH daemon. Do not install or enable SSH within a container (see *Process*s). Use docker attach to log into a container if needed for debugging. On top of that, optimize your logging.

✅ Shutdown: avoid canceling requests and jobs

Your application receives KILL signals and shuts down gracefully. Test whether the KILL signal triggered by docker kill leads to your application stopping to answer new requests or start new jobs and terminate after the last request or job has been completed.

Does your Dockerfile contain ENTRYPOINT or CMD in shell form? Your main process will not receive any KILL signals.
Are you starting your main process from a shell script? Make sure you are using exec to do so.

When using Fargate it is necessary, that your application is able to shutdown gracefully within 2 minutes.

🎉 Summary

Checked all five requirements from the checklist? Happy you! Your application is ready for ECS and Fargate or any other container cluster solution.

📚 eBook and Online Seminar

Do you want to learn more about how to ship your application with Docker? Our ebook and online seminar Rapid Docker on AWS teaches you how to dockerize PHP, Ruby on Rails, Python Django, Java Spring Boot, and Node.js Express applications.

How to dockerize your Python Django application for AWS Fargate?

Andreas Wittig — Tue, 19 Nov 2019 16:06:34 +0000

The biggest game-changer for Docker on AWS was the announcement of AWS Fargate. Operating Docker containers could not be easier. With AWS Fargate, you launch Docker containers in the cloud without any need to manage virtual machines. Django is a popular Python web framework that encourages rapid development and clean, pragmatic design.

This blog post is an excerpt from our book Rapid Docker on AWS and was first published on cloudonaut.io.

The following post describes how you can dockerize your Python Django application and run it on AWS Fargate.

Building the Docker images

Two Docker images are needed:

NGINX to serve static files and proxy to Django
Python Django application

First, you will learn how to build NGINX image. The Dockerfile makes use of multi-stage builds. You can use more than one FROM statement in your Dockerfile, as shown in the following example.

Static assets are generated in a Python stage
1. Based on the official python image
2. Using pip3 to install the Python dependencies
3. Copying the app
4. Generating the static assets with python3 manage.py collectstatic (output goes to the assets folder)
The static assets are copied (using COPY --from=build) into the NGINX stage which produces the final Docker image
1. Based on the official nginx image
2. Copying the static/ folder from the previous stage

Customization Most likely, your folder structure is different. Therefore, adapt the Copy Python files section in the following Dockerfile to your needs.

# Static Assets
FROM python:3.7.4 AS build

WORKDIR /usr/src/app

# Install Python dependencies
COPY requirements.txt /usr/src/app/
RUN pip3 install -r requirements.txt

# Copy Python files
COPY example /usr/src/app/example # MODIFY THIS LINE: YOUR FOLDERS ARE DIFFERENT
COPY rapid /usr/src/app/rapid # MODIFY OR REMOVE THIS LINE: YOUR FOLDERS ARE DIFFERENT
COPY manage.py /usr/src/app/

# Build static assets
RUN SECRET_KEY=secret python3 manage.py collectstatic


# NGINX
FROM nginx:1.14

# Configure NGINX
COPY docker/nginx/default.conf /etc/nginx/conf.d/default.conf

# Copy static files
COPY --from=build /usr/src/app/build/ /var/www/html/static
RUN chown -R nginx:nginx /var/www/html

The NGINX configuration file forwards requests to the Python container if the path does not start with /static/.

server {
    listen       80;
    server_name  localhost;
    root         /var/www/html;

    location ~ ^/static/ {
      # serve from NGINX
    }

    location / {
      # pass to Python gunicorn based on
      # http://docs.gunicorn.org/en/stable/deploy.html
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header Host $http_host;
      # we don't want nginx trying to do something clever with
      # redirects, we set the Host: header above already.
      proxy_redirect off;
      proxy_pass http://127.0.0.1:8000;
    }
}

Next, you will learn how to create the Django imge. The Dockerfile is based on the official python image with the following additions:

wait-for-it is installed to wait for the MySQL database container if you test locally.
Python dependencies are installed with pip3 install.
A custom etrypoint is defined to run commands before the Django app starts (read on to learn more).
gunicorn runs the app.

Customization Most likely, your folder structure is different. Therefore, adapt the Copy Python files section in the following Dockerfile to your needs.

FROM python:3.7.4

WORKDIR /usr/src/app

# Install wait-for-it
COPY docker/wait-for-it.sh /usr/local/bin/
RUN chmod u+x /usr/local/bin/wait-for-it.sh

# Install Python dependencies
COPY requirements.txt /usr/src/app/
RUN pip3 install -r requirements.txt

# Copy Python files
COPY example /usr/src/app/example # MODIFY THIS LINE: YOUR FOLDERS ARE DIFFERENT
COPY rapid /usr/src/app/rapid # MODIFY THIS LINE: YOUR FOLDERS ARE DIFFERENT
COPY manage.py /usr/src/app/

# Configure custom entrypoint to run migrations
COPY docker/python/custom-entrypoint /usr/local/bin/
RUN chmod u+x /usr/local/bin/custom-entrypoint
ENTRYPOINT ["custom-entrypoint"]

# Expose port 8000 and start Python server
EXPOSE 8000
CMD ["gunicorn", "-b", "0.0.0.0", "-w", "2", "rapid.wsgi"]

Customization The -w parameter of gunicorn defines the number of workers and should be in the range of 2-4 x $(NUM_CORES).

The custom entrypoint is used to:

Wait for the MySQL container if the WAIT_FOR_IT environment variable is set (used for testing locally only).
Run the database migrations before the Django app is started.

#!/bin/bash
set -e

if [ -n "${WAIT_FOR_IT}" ]; then
  wait-for-it.sh mysql:3306
fi

echo "running migrations"
python3 manage.py migrate

echo "starting $@"
exec "$@"

That's it. You have everything you need to build both, the NGINX as well as the Django image. Next, you will learn how to test your containers and application locally.

Testing locally

Use Docker Compose to run your application locally. The following docker-compose.yml file configures Docker Compose and starts three containers: NGINX, Django as well as a MySQL database.

version: '3'
services:
  nginx:
    build:
      context: '..'
      dockerfile: 'docker/nginx/Dockerfile'
    depends_on:
    - python
    network_mode: 'service:python' # use network interface of python container to simulate awsvpc network mode
  python:
    build:
      context: '..'
      dockerfile: 'docker/python/Dockerfile'
    ports:
    - '8080:80' # forwards port of nginx container
    depends_on:
    - mysql
    environment:
      DATABASE_HOST: mysql
      DATABASE_NAME: app
      DATABASE_USER: app
      DATABASE_PASSWORD: secret
      SECRET_KEY: secret
      WAIT_FOR_IT: 'true'
  mysql:
    image: 'mysql:5.6'
    command: '--default-authentication-plugin=mysql_native_password'
    ports:
    - '3306:3306'
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: app
      MYSQL_USER: app
      MYSQL_PASSWORD: secret

The following command starts the application:

docker-compose -f docker/docker-compose.yml up --build

After you have verified that your application is working correctly, cancel the running docker-compose process by pressing CTRL + C, and tear down the containers:

docker-compose -f docker/docker-compose.yml down

Deploying on AWS

You are now ready to deploy your application on AWS.

(1) Build Docker images:

docker build -t python-django-nginx:latest \
  -f docker/nginx/Dockerfile .
docker build -t python-django-python:latest \
  -f docker/python/Dockerfile .

(2) Create ECR repositories:

aws ecr create-repository --repository-name python-django-nginx \
  --query 'repository.repositoryUri' --output text
aws ecr create-repository --repository-name python-django-python \
  --query 'repository.repositoryUri' --output text

(3) Login to Docker registry (ECR):

$(aws ecr get-login --no-include-email)

(4) Tag Docker images:

docker tag python-django-nginx:latest \
111111111111.dkr.ecr.eu-west-1.amazonaws.com/\
python-django-nginx:latest
docker tag python-django-python:latest \
111111111111.dkr.ecr.eu-west-1.amazonaws.com/\
python-django-python:latest

(5) Push Docker images:

docker push \
111111111111.dkr.ecr.eu-west-1.amazonaws.com/\
python-django-nginx:latest
docker push \
111111111111.dkr.ecr.eu-west-1.amazonaws.com/\
python-django-python:latest

There is only one step missing: you need to spin up the cloud infrastructure.

Use our Free Templates for AWS CloudFormation.
Use our cfn-modules.
Use the blueprint from our book Rapid Docker on AWS.

Rapid Docker on AWS: How to monitor the application?

Andreas Wittig — Fri, 08 Nov 2019 19:33:51 +0000

Gaining insights into your infrastructure and application is crucial for debugging issues and avoiding failures. The following figure shows that all parts of the infrastructure are sending metrics to a service called Amazon CloudWatch. The metrics include CPU utilization of your containers, the number of database connections, the number of HTTP 5XX errors caused by the load balancer, and many more. Alarms monitor relevant metrics and send notifications to SNS (Amazon Simple Notification Service). SNS delivers the alarm notifications to you via email or other destinations.

The following alarms make sure you are the first to know when your web application is not working as expected:

HTTPCodeELB5XXTooHighAlarm: An HTTP request was answered with a 5XX status code (server-side error) by the load balancer, most likely because there was no healthy container running.

TargetConnectionErrorCountTooHighAlarm: The load balancer was not able to establish a connection to one of the containers.

HTTPCodeTarget5XXTooHighAlarm: Your application responded with a 5XX status code (server-side error).

RejectedConnectionCountTooHighAlarm: A client connection to the load balancer was rejected.

CPUUtilizationTooHighAlarm: The CPU utilization of your containers is too high.

Our goal is to send alarm notifications only when the user experience is affected. However, you might want to get an overview of the state and utilization of your infrastructure from time to time. Use the predefined CloudWatch dashboard as illustrated in the screenshot below to do so. The dashboard includes:

ALB Errors: the 4XX (client-side) and 5XX (server-side) error rate of your web application.
ALB Requests + Latency: the number of requests, as well as the latency (99 and 95 percentiles).
ECS Utilization: the CPU and memory utilization of your containers.
RDS IOPS + Capacity: the capacity of your database, as well as the I/O throughput (IOPS).
RDS Latency: the latency of SELECT, INSERT, UPDATE, and DELETE statements.
RDS Queries: the number of SELECT, INSERT, UPDATE, and DELETE statements.

Execute the following command from your working environment to fetch the dashboard's URL.

aws cloudformation describe-stacks --stack-name rapid-docker-on-aws \
  --query 'Stacks[0].Outputs[?OutputKey==`DashboardUrl`].OutputValue' \
  --output text

In summary, metrics and alarms allow you to monitor your cloud infrastructure and web application. One important piece for debugging is missing: log messages. As shown in the following figure, whenever your application writes a message to standard output (stdout) and standard error (stderr), these messages are automatically pushed to a log group in CloudWatch Logs. The log group collects all the log messages and stores them for 14 days. On top of that, you can search and analyze the log messages for debugging purposes whenever needed.

Execute the following command from your working environment to fetch the URL pointing to CloudWatch Logs Insights.

aws cloudformation describe-stacks --stack-name rapid-docker-on-aws \
  --query 'Stacks[0].Outputs[?OutputKey==`AppLogsUrl`].OutputValue' \
  --output text

The following screenshot shows CloudWatch Logs Insights in action:

To search through your logs, you need to:

Modify the query.
Select a time span.
Hit the Run query button.

Warning Choose a time span as short as possible to avoid unnecessary costs when searching the log messages.

Let's start with a simple query filtering all log messages from the proxy container (NGINX):

fields @timestamp, @message
| sort @timestamp desc
| filter @logStream like 'proxy/'

And a similar query to filter all log messages from the app container (e.g., PHP-FPM):

fields @timestamp, @message
| sort @timestamp desc
| filter @logStream like 'app/'

This more advanced query filters all log messages from the proxy container (e.g., NGINX) containing the search term “404” in the log message:

fields @timestamp, @message
| sort @timestamp desc
| filter @logStream like 'proxy/' AND @message like '404'

Another example: this query filters all log messages from the app container (e.g., PHP-FPM) containing the search term “error” in the log message:

fields @timestamp, @message
| sort @timestamp desc
| filter @logStream like 'app/' AND @message like 'error'

Want to learn more about the query syntax? Check out the CloudWatch Logs Insights Query Syntax.

In summary, with CloudWatch metrics, alarms, and logs, monitoring and debugging your web application is simple.

Do you have any questions? Please leave them in the comments. This is the last post of a series. Follow me to make sure you are not missing the following posts.

This post is an excerpt from our new book Rapid Docker on AWS. The book includes code samples for PHP, Ruby (Rails), Python (Django), Java (Spring Boot), and Node.js (Express).

Rapid Docker on AWS: How to set up the AWS infrastructure?

Andreas Wittig — Thu, 07 Nov 2019 19:17:51 +0000

The secret sauce allowing you to set up your cloud infrastructure within minutes, which consists of around 100 resources, is Infrastructure as Code. It removes the need for clicking through the AWS Management Console manually.

In our opinion, Infrastructure as Code works best when following the declarative approach. Define the target state in source code and use a tool which calculates and executes the needed steps to transform the current state into the target state. Our tool of choice is AWS CloudFormation.

The figure below explains the key concepts of CloudFormation.

You create a JSON or YAML file describing the target state of your infrastructure, which CloudFormation calls a template.
You upload your template and ask CloudFormation to create, update or delete your infrastructure. The state of your infrastructure is stored within a so-called stack.
CloudFormation transforms the current state of your stack into the target state defined in your template. To do so, CloudFormation creates, updates, or deletes resources as needed.

First, install the CloudFormation modules. To do so, create a package.json file with the following content.

{
  "name": "rapid-docker-on-aws-rapid-docker-on-aws",
  "version": "1.0.0",
  "description": "Rapid Docker on AWS: Demo",
  "author": "Michael Wittig <michael@widdix.de>",
  "license": "Apache-2.0",
  "private": true,
  "dependencies": {
    "@cfn-modules/alb": "1.0.4",
    "@cfn-modules/alb-listener": "1.0.0",
    "@cfn-modules/alerting": "1.2.0",
    "@cfn-modules/client-sg": "1.0.0",
    "@cfn-modules/cloudwatch-dashboard": "1.2.0",
    "@cfn-modules/ecs-cluster": "1.1.0",
    "@cfn-modules/ecs-alb-target": "1.2.0",
    "@cfn-modules/fargate-service": "2.5.0",
    "@cfn-modules/kms-key": "1.2.0",
    "@cfn-modules/rds-aurora-serverless": "1.5.0",
    "@cfn-modules/secret": "1.3.0",
    "@cfn-modules/vpc": "1.1.1"
  }
}

Next, create the CloudFormation template. To do so, create a template.yml file with the following content.

---
AWSTemplateFormatVersion: '2010-09-09'
Description: 'Rapid Docker on AWS: Demo application'
Parameters:
  AppImage:
    Description: 'The Docker image to use for the app container.'
    Type: String
    Default: 'cloudonaut/docker-on-aws-rapid-docker-on-aws-php-fpm:latest'
  ProxyImage:
    Description: 'Docker image to use for the proxy container.'
    Type: String
    Default: 'cloudonaut/docker-on-aws-rapid-docker-on-aws-nginx:latest'
  AdminEmail:
    Description: 'Optional email address of the administrator.'
    Type: String
    Default: ''
Conditions:
  HasAdminEmail: !Not [!Equals ['', !Ref AdminEmail]]
Resources:
  Alerting:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        Email: !If [HasAdminEmail, !Ref AdminEmail, !Ref 'AWS::NoValue']
      TemplateURL: './node_modules/@cfn-modules/alerting/module.yml'
  Dashboard:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        DashboardName: !Ref 'AWS::StackName'
        AlbModule: !GetAtt 'Alb.Outputs.StackName'
        FargateServiceModule: !GetAtt 'AppService.Outputs.StackName'
        RdsAuroraServerlessModule: !GetAtt 'AuroraServerlessCluster.Outputs.StackName'
      TemplateURL: './node_modules/@cfn-modules/cloudwatch-dashboard/module.yml'
  Key:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        AlertingModule: !GetAtt 'Alerting.Outputs.StackName'
      TemplateURL: './node_modules/@cfn-modules/kms-key/module.yml'
  DatabaseSecret:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        KmsKeyModule: !GetAtt 'Key.Outputs.StackName'
        Description: !Sub '${AWS::StackName}: database password'
      TemplateURL: './node_modules/@cfn-modules/secret/module.yml'
  Vpc:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        AlertingModule: !GetAtt 'Alerting.Outputs.StackName'
        NatGateways: 'false' # reduce costs
      TemplateURL: './node_modules/@cfn-modules/vpc/module.yml'
  AuroraServerlessClientSg:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        VpcModule: !GetAtt 'Vpc.Outputs.StackName'
      TemplateURL: './node_modules/@cfn-modules/client-sg/module.yml'
  AuroraServerlessCluster:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        VpcModule: !GetAtt 'Vpc.Outputs.StackName'
        ClientSgModule: !GetAtt 'AuroraServerlessClientSg.Outputs.StackName'
        KmsKeyModule: !GetAtt 'Key.Outputs.StackName'
        AlertingModule: !GetAtt 'Alerting.Outputs.StackName'
        SecretModule: !GetAtt 'DatabaseSecret.Outputs.StackName'
        DBName: test
        DBMasterUsername: master
        SecondsUntilAutoPause: '900'
        MinCapacity: '1'
        MaxCapacity: '2'
        EngineVersion: '5.6.10a'
      TemplateURL: './node_modules/@cfn-modules/rds-aurora-serverless/module.yml'
  Alb:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        VpcModule: !GetAtt 'Vpc.Outputs.StackName'
        AlertingModule: !GetAtt 'Alerting.Outputs.StackName'
      TemplateURL: './node_modules/@cfn-modules/alb/module.yml'
  AlbListenerHttp:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        AlbModule: !GetAtt 'Alb.Outputs.StackName'
        Port: '80'
      TemplateURL: './node_modules/@cfn-modules/alb-listener/module.yml'
  AppTarget:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        AlbModule: !GetAtt 'Alb.Outputs.StackName'
        AlbListenerModule: !GetAtt 'AlbListenerHttp.Outputs.StackName'
        VpcModule: !GetAtt 'Vpc.Outputs.StackName'
        AlertingModule: !GetAtt 'Alerting.Outputs.StackName'
        Priority: '2'
        HealthCheckPath: '/health-check.php'
      TemplateURL: './node_modules/@cfn-modules/ecs-alb-target/module.yml'
  Cluster:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      TemplateURL: './node_modules/@cfn-modules/ecs-cluster/module.yml'
  AppService:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      Parameters:
        VpcModule: !GetAtt 'Vpc.Outputs.StackName'
        ClusterModule: !GetAtt 'Cluster.Outputs.StackName'
        TargetModule: !GetAtt 'AppTarget.Outputs.StackName'
        AlertingModule: !GetAtt 'Alerting.Outputs.StackName'
        ClientSgModule1: !GetAtt 'AuroraServerlessClientSg.Outputs.StackName'
        ProxyImage: !Ref ProxyImage
        ProxyPort: '80'
        AppImage: !Ref AppImage
        AppPort: '9000'
        AppEnvironment1Key: 'DATABASE_PASSWORD'
        AppEnvironment1SecretModule: !GetAtt 'DatabaseSecret.Outputs.StackName'
        AppEnvironment2Key: 'DATABASE_HOST'
        AppEnvironment2Value: !GetAtt 'AuroraServerlessCluster.Outputs.DnsName'
        AppEnvironment3Key: 'DATABASE_NAME'
        AppEnvironment3Value: 'test'
        AppEnvironment4Key: 'DATABASE_USER'
        AppEnvironment4Value: 'master'
        Cpu: '0.25'
        Memory: '0.5'
        DesiredCount: '2'
        MaxCapacity: '4'
        MinCapacity: '2'
        LogsRetentionInDays: '14'
      TemplateURL: './node_modules/@cfn-modules/fargate-service/module.yml'
Outputs:
  Url:
    Value: !Sub 'http://${Alb.Outputs.DnsName}/'
  AlbDnsName:
    Value: !GetAtt 'Alb.Outputs.DnsName'
  DashboardUrl:
    Value: !Sub 'https://${AWS::Region}.console.aws.amazon.com/cloudwatch/home?region=${AWS::Region}#dashboards:name=${AWS::StackName}'
  AppLogsUrl:
    Value: !Sub "https://${AWS::Region}.console.aws.amazon.com/cloudwatch/home?region=${AWS::Region}#logs-insights:queryDetail=~(source~(~'${AppService.Outputs.LogGroupName}))"

Finally, you will deploy the demo web application into your AWS account.

Warning Costs arise when you launch the demo infrastructure and application. You can expect costs of around $4.50 per day.

In your temporary working environment (replace $NICKNAME), execute the following commands:

npm i
aws s3 mb s3://rapid-docker-on-aws-$NICKNAME
aws cloudformation package --template-file template.yml \
  --s3-bucket rapid-docker-on-aws-$NICKNAME \
  --output-template-file .template.yml
aws cloudformation deploy --template-file .template.yml \
  --stack-name rapid-docker-on-aws --capabilities CAPABILITY_IAM

The last command takes around 20 minutes to complete with an output like this:

Waiting for changeset to be created..
Waiting for stack create/update to complete
Successfully created/updated stack - rapid-docker-on-aws

The AWS resources are created. The following command fetches the URL:

aws cloudformation describe-stacks --stack-name rapid-docker-on-aws \
  --query 'Stacks[0].Outputs[?OutputKey==`Url`].OutputValue' \
  --output text

The output looks like this:

http://demo-LoadB-[...].elb.amazonaws.com

Open the URL in your web browser. Remember all the benefits of the Rapid Docker on AWS architecture. Isn't it amazing how easy you can launch this architecture?

It's time to delete the running demo web application to avoid future costs. Execute the following commands (replace $NICKNAME):

aws cloudformation delete-stack --stack-name rapid-docker-on-aws
aws s3 rb --force s3://rapid-docker-on-aws-$NICKNAME

Do you have any questions? Please leave them in the comments. This is the 4th post of a series. Follow me to make sure you are not missing the following posts.

This post is an excerpt from our new book Rapid Docker on AWS. The book includes code samples for PHP, Ruby (Rails), Python (Django), Java (Spring Boot), and Node.js (Express).

Rapid Docker on AWS: How to test locally?

Andreas Wittig — Wed, 06 Nov 2019 20:03:15 +0000

As promised one of the benefits of Docker is that you can test your application locally. To do so, you need to spin up three containers:

NGINX
PHP-FPM
MySQL (which will be replaced by Amazon Aurora when deploying on AWS)

Theoretically, you can create the needed containers manually with docker run but doing so is a little cumbersome. You will use Docker Compose, a tool for running multi-container applications, instead.

All you need to do is to create a Docker Compose file docker-compose.yml.

Customization You probably need to add your own environment variables for the PHP container (see inline comments).

version: '3'
services:
  nginx:
    build:
      context: '..'
      dockerfile: 'docker/nginx/Dockerfile' # build your NGINX image
    depends_on:
    - php
    network_mode: 'service:php' # use network interface of php container to simulate awsvpc network mode
  php:
    build:
      context: '..'
      dockerfile: 'docker/php-fpm/Dockerfile' # build PHP image
    ports:
    - '8080:80' # forwards port of nginx container
    depends_on:
    - mysql
    environment: # add your own variables used by envsubst here
      DATABASE_HOST: mysql
      DATABASE_NAME: app
      DATABASE_USER: app
      DATABASE_PASSWORD: secret
  mysql:
    image: 'mysql:5.6' # matches the Amazon Aurora MySQL version
    command:'--default-authentication-plugin=mysql_native_password'
    ports:
    - '3306:3306' # forwards port 3306 to 3306 on your machine
    environment:
      MYSQL_ROOT_PASSWORD: secret # password for root user
      MYSQL_DATABASE: app # create database with name app
      MYSQL_USER: app # user app is granted full access to db app
      MYSQL_PASSWORD: secret # the password for user app

From within your temporary working environment execute the following command to spin up the containers on your machine.

docker-compose -f docker/docker-compose.yml up

Magically, Docker Compose will spin up three containers. Point your browser to http://localhost:8080/index.php to check that your web application is up and running. The log files of all containers will show up in your terminal which simplifies debugging a lot.

If you need to make a change to your setup, please cancel the running docker-compose process CTRL + C and restart with the following command afterwards to make sure the images get re-built.

docker-compose -f docker/docker-compose.yml up --build

Use your favorite MySQL client and connect to localhost:3306 with username root and password secret if you need to create a schema or restore a database dump.

After you have verified that your application is working correctly, cancel the running docker-compose process by pressing CTRL + C, and tear down the containers.

docker-compose -f docker/docker-compose.yml down

It's time to deploy your web application on AWS. You will learn how to to so in the next part of this series.

Do you have any questions? Please leave them in the comments. This is the 3rd post of a series. Follow me to make sure you are not missing the following posts.

This post is an excerpt from our new book Rapid Docker on AWS. The book includes code samples for PHP, Ruby (Rails), Python (Django), Java (Spring Boot), and Node.js (Express).

Rapid Docker on AWS: How to build a Docker image?

Andreas Wittig — Tue, 05 Nov 2019 19:18:08 +0000

Shipping software is a challenge. Endless installation instructions explain in detail how to install and configure an application as well as all its dependencies. But in practice, following installation instructions ends with frustration: the required version of PHP is not available to install from the repository, the configuration file is located in another directory, the installation instructions do not cover the operating system you need or want to use, etc.

And it gets worse: to be able to scale on demand and recover from failure on AWS we need to automate the installation and configuration of our application and its runtime environment. Implementing the required automation with the wrong tools is very time-consuming and error-prone.

In short: Docker is a toolkit to deliver software.

Or as Jeff Nickoloff explains in Docker in Action (Manning): "Docker is a command-line program, a background daemon, and a set of remote services that take a logistical approach to solving common software problems and simplifying your experience installing, running, publishing, and removing software. It accomplishes this using a UNIX technology called containers."

You will learn how to use Docker to ship your web application to AWS in this part of the series. Most importantly, we will show you how to build Docker images to bundle your web application.

Before we proceed, I want to highlight a few essential best practices when working with Docker containers.

Use one process per container. If your application consists of more than one process, split them up into multiple containers. For example, if you run NGINX and PHP-FPM, create two containers. The PHP example in the following section shows how to do that.
Do not use SSH. Do not install or enable SSH within a container. Use docker attach to log into a container if needed for debugging. Or even better, optimize logging for debugging.
Use environment variables instead of configuration files. Do not use files to store the configuration for your application. Use environment variables instead. We will cover how to do so in the following section.
Use standard output (stdout) and standard error (stderr) for logging. Do not write log files. Docker has built-in support to ship log messages from STDOUT and STDERR to various centralized logging solutions.

With Docker containers the differences between different platforms like your developer machine, your test system, and your production system are hidden under an abstraction layer. But how do you distribute your application with all its dependencies to multiple platforms? By creating a Docker image. A Docker image is similar to a virtual machine image, such as an Amazon Machine Image (AMI) that is used to launch an EC2 instance. The Docker image contains an operating system, the runtime environment, 3rd party libraries, and your application. The following figure illustrates how you can fetch an image and start a container on any platform.

But how do you create a Docker image for your web application? By creating a script that builds the image step by step: a so called Dockerfile.

In the following example you will learn how to dockerize your web application. The example uses a simple web application written in PHP without using any frameworks.

The sample application uses the following project structure:

conf the configuration directory (contains .ini files)
css the stylesheet directory (contains .css files)
img the images directory (contains .gif files)
lib the libraries directory (contains .php files)
index.php the main file

A typical setup to serve a PHP application consists of:

A web server (for example NGINX)
A PHP process (for example PHP-FPM)

Therefore, we need to run two processes: NGINX and PHP-FPM. However, a container should only run exactly one process at a time. Which means we need to build two images. The following figure shows the two containers: the NGINX container receives the request from the client and forwards PHP requests to the PHP-FPM container. Both containers run on the same host to avoid additional network latency.

Start with creating a Docker image for NGINX. NGINX serves the static files. In our example application the static files are stored in the css and img directory already. On top of that, NGINX forwards PHP requests to PHP-FPM.

The following snippet shows the configuration file docker/nginx/default.conf which tells NGINX to serve static files from /var/www/html and forward PHP requests to PHP-FPM. You do not need to make any changes to the NGINX configuration when dockerizing your web application.

server {
    listen       80;
    server_name  localhost;
    root         /var/www/html;
    # pass the PHP scripts to FastCGI server
    # listening on 127.0.0.1:9000
    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
        fastcgi_param  SCRIPT_NAME      $fastcgi_script_name;
        include        fastcgi_params;
    }
    # redirect / to index.php
    location ~ ^\/$ {
        return 301 $scheme://$http_host/index.php$is_args$args;
    }
}

Next, you need a Dockerfile for building your own NGINX image. The following snippet shows the file docker/nginx/Dockerfile that we created for our sample application.

The first instruction defines the base image. When creating an image, we don't have to start from scratch. We can use a pre-built base image.

FROM nginx:1.14

The next instruction copies the NGINX configuration file from your disk to the Docker image.

COPY docker/nginx/default.conf /etc/nginx/conf.d/default.conf

The next two instructions copy the css and img directories from your local disk to the NGINX root directory /var/www/html/ in the Docker image.

Customization Depending on where you are storing the static files of your web application, you'll need to modify these instructions accordingly. Make sure you are copying all static files to /var/www/html/.

COPY css /var/www/html/css
COPY img /var/www/html/img

The next instruction runs the chown command to transfer ownership of all static files to the nginx user. The nginx user is part of the base image.

RUN chown -R nginx:nginx /var/www/html

The Dockerfile is ready. It's time to build your first image.

docker build -t php-basic-nginx:latest -f docker/nginx/Dockerfile .

The following table explains the parameters of the docker build command to build a new image:

Parameter	Explanation
`-t php-basic-nginx:latest`	Add a tag (name) to the new image.
`-f docker/nginx/Dockerfile`	Location of the Dockerfile.
`.`	Use the current directory as the build context (all paths, e.g. in COPY, are relative to the build context).

The next step is building the PHP-FPM image. The following snippets show the file docker/php-fpm/Dockerfile used by our sample application.

The first instruction defines the base image. We are using a base image with PHP 7.3 pre-installed for our sample application.

Customization The following versions are supported as well: 7.2 and 7.1.

FROM php:7.3-fpm-stretch

Followed by enabling the PHP configuration optimized for production workloads and installing the PHP extensions pdo and pdo_mysql.

Customization Feel free to install additional extensions if needed.

RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
RUN docker-php-ext-install -j$(nproc) pdo pdo_mysql

The next commands install envsubst. You will learn more about how to create configuration files with envsubst in a second. No need to change anything here.

RUN apt-get update && apt-get install -y gettext
COPY docker/php-fpm/custom-entrypoint /usr/local/bin/
RUN chmod u+x /usr/local/bin/custom-entrypoint
ENTRYPOINT ["custom-entrypoint"]
RUN mkdir /var/www/html/conf/

Afterwards, the script copies all configuration templates .tmp located in conf/.

COPY conf/*.tmp /tmp/conf/

The following instructions copy the PHP files from your disk to the root directory of PHP-FPM.

Customization When dockerizing your own application you will most likely need to modify these COPY instructions to make sure all PHP files are copied to the image. Also, as you add new PHP files to your application, make sure to add them to this list as well.

COPY *.php /var/www/html/
COPY lib /var/www/html/lib
RUN chown -R www-data:www-data /var/www/html

The last instruction tells Docker to start the PHP-FPM process by default. You do not need to change anything here.

CMD ["php-fpm"]

The Dockerfile is ready. But we have skipped one challenge: the configuration files. We assume you are storing the configuration for your web application within files. When using Docker, and especially when using Fargate, using configuration files is cumbersome. Instead, you should use environment variables to configure your application.

You have two options:

Modify your application to read all configuration from environment variables.
Do not modify your application, but use environment variables to create configuration files with envsubst.

In the following steps you will learn how to write configuration files on container startup based on environment variables with envsubst.

Our sample application uses a configuration file to configure the database connection: conf/app.ini

[database]
host=mysql
name=test
user=app
password=secret

Our goal is to use environment variables for each property. To do so with envsubst, we need to create a configuration template. The following snippet shows the template conf/app.ini.tmp for our conf/app.ini configuration file.

In the template, each value has been replaced with a placeholder. For example, ${DATABASE_HOST} references the environment variable DATABASE_HOST.

[database]
host="${DATABASE_HOST}"
name="${DATABASE_NAME}"
user="${DATABASE_USER}"
password="${DATABASE_PASSWORD}"

By default, the Dockerfile adds all configuration template files .tmp stored in conf to the image. Each time a container starts it executes the script located in docker/php-fpm/custom-entrypoint. The following snippet shows how the custom-entrypoint script creates the configuration files based on all your configuration templates.

echo "generating configuration files"
FILES=/tmp/conf/*
for f in $FILES
do
  c=$(basename $f .tmp)
  echo "... $c"
  envsubst < $f > /var/www/html/conf/${c}
done

Customization To add your own configuration files, create a configuration template by replacing all dynamic values with placeholders (e.g. $ENV_NAME). Store the configuration template in the conf folder. That's it. During runtime the container will create a configuration file based on the template.

Next, use the docker build command to create your PHP-FPM image:

docker build -t php-basic-php-fpm:latest \
  -f docker/php-fpm/Dockerfile .

You have successfully built two Docker images. You will learn how to test your Docker images locally in the 3rd part of the series.

Do you have any questions? Please leave them in the comments. This is the 2nd post of a series. Follow me to make sure you are not missing the following posts.

This post is an excerpt from our new book Rapid Docker on AWS. The book includes code samples for PHP, Ruby (Rails), Python (Django), Java (Spring Boot), and Node.js (Express).

Rapid Docker on AWS: Which option to choose?

Andreas Wittig — Mon, 04 Nov 2019 20:12:09 +0000

AWS offers more than 100 services. So much choice is both a curse and a blessing. For example, there are at least four options to run containers on AWS: the Elastic Container Service (ECS), the Elastic Kubernetes Services (EKS), operate your own cluster on top of EC2, and Elastic Beanstalk. Futhermore, you can choose between a lot of database services: RDS, Aurora, DynamoDB, DocumentDB, Elasticsearch, Neptune, Redshift, ElastiCache, to name a few.

But before you make your choice, you should think about the goals for your cloud-native architecture.

When designing the Rapid Docker on AWS architecture, we had one goal in mind: a production-ready infrastructure for everyone. We went through a long, iterative design process. We were inspired by numerous customer projects where customers asked us to minimize operational effort or shorten time to market. For years, we have been waiting for new AWS features that would help us achieve our ultimate goal. Now, we are happy to share our solution, which has the following benefits.

Low operational effort

All AWS building blocks used in the architecture described in this book are fully managed services causing minimal operational effort. You don't have to sign TLS certificates or install a database engine. You only have to care about your Docker image with your configuration, source code, and dependencies. AWS even takes care of your data by performing daily backups. AWS also covers security aspects, such as data encryption in-transit (using HTTPS/TLS) and at-rest. In a nutshell, you don't need highly specialized people on your team to operate the infrastructure.

Ready for the future

Architectures are not static anymore. An evolutionary architecture evolves with new requirements. When making use of infrastructure as code (IaC), you can deploy changes to your architecture with confidence. IaC enables you to test changes to your architecture before you apply them to production.

Cost-effective

In an ideal world, you only pay when your system is processing a user request. You never want to pay for idle resources. The architecture described in this book minimizes your costs for idle resources. The database can stop if not used, and you only run as few containers as possible to provide the needed performance.

Highly available

Sooner or later, a single point of failure causes an outage. This Rapid Docker on AWS architecture has no single point of failure and uses redundant components everywhere, from the load balancer to the multiple containers running on different hosts to the redundant database cluster.

Scalable

Your infrastructure is only as powerful as your weakest component. It is not sufficient to scale your web servers to handle a growing amount of requests. You have to scale your database as well. That's why the architecture described in this book scales the whole stack: the load balancer, the Docker containers running web servers, and the database.

Overview of the architecture

The main building blocks of the Rapid Docker on AWS architecture are:

A load balancer: Application Load Balancer (ALB)
Docker containers: Amazon ECS & AWS Fargate
A database: Amazon Aurora Serverless (MySQL-compatible edition)

The following figure shows the high-level architecture:

Next, you will learn more about the main building blocks.

Application Load Balancer

The Application Load Balancer (ALB) distributes HTTP and HTTPS requests among a group of hosts. In our case, the hosts are Docker containers running a web server. An ALB is highly available and scalable by default, and it serves as the entry point into your infrastructure. The traffic flows from the client to your containers as follows:

The client makes an HTTP(S) request to the load balancer.
The load balancer receives the request and distributes it to one of the containers running a web server.
The containerized web server receives the request, does some processing, and sends a response.
The load balancer receives the response and forwards it to the client.
The client receives the response.

ALB pricing is based on two dimensions. First, you pay $0.0225 per hour (or partial hour) no matter how much traffic it serves. Second, you pay for the higher number of new connections, active connections, or traffic.

Continue on to learn about the Docker aspect of the architecture.

Amazon ECS & AWS Fargate

Amazon ECS is a fault-tolerant and scalable Docker container management service that is responsible for managing the lifecycle of a container. It supports two different modes or "launch types," one of which is AWS Fargate, which eliminates the need for managing a cluster of EC2 instances yourself. Instead, the cluster is managed by AWS, allowing you to focus on the containers rather than on the underlying infrastructure.

ECS is free of charge. Fargate pricing is based on the allocated vCPU and memory over time. A vCPU costs $0.04048 per hour and a GB of memory costs $0.004445 per hour. If you provision 0.25 vCPU and 0.5 GB memory for your container, it costs you $8.89 per month (30 days). To avoid a single point of failure, you should always run two containers at a time, totaling $17.78 per month. Pricing is per second with a minimum of 1 minute.

Amazon Aurora Serverless

Amazon Aurora Serverless is a highly available, scalable, MySQL 5.6-compatible relational database cluster. Depending on the load (CPU utilization and the number of connections), the cluster grows or shrinks within configurable boundaries. Aurora Serverless can scale down to zero when there are no connections for a configurable timespan.

Aurora Serverless pricing is based on three dimensions:

Compute and memory capacity measured in Aurora Capacity Units (ACUs). One ACU has approximately 2 GB of memory with an undocumented share of CPU and networking. You pay $0.06 per ACU per hour with a minimum of one ACUs per cluster. If the cluster is stopped you consume zero ACUs.
Storage: $0.10 per GB per month.
I/O rate: $0.20 per 1 million requests.

If your database is of modest size (e.g., 50 GB), you would pay $5 per month for storage. On average, two ACUs should be sufficient for a modest database, which costs another $86.40 per month if your database runs 24/7. However, many databases are not needed 24/7 and can be stopped if not used like dev systems or internal systems that are used during working hours only.

You have learned about a simple and powerful architecture for your web application consisting of an Application Load Balancer (ALB), ECS, Fargate, and Aurora Serverless.

Do you have any questions? Please leave them in the comments. This is the 1st post of a series. Follow me to make sure you are not missing the following posts.

This post is an excerpt from our new book Rapid Docker on AWS. The book includes code samples for PHP, Ruby (Rails), Python (Django), Java (Spring Boot), and Node.js (Express).