We divided a project into multiple services running in Docker containers. We used Ansible to create base Docker images and Docker Compose to configure and run the containers. Bitbucket Pipelines was used to build and deploy the containers to Amazon ECS, which runs the containers across an auto-scaling group of EC2 instances behind a load balancer. Nginx maps requests to the appropriate versioned PHP-FPM container based on the Accept header to support API versioning.

1. API Versioning 1.0.501
With Docker And Nginx
Using every tool in the box

2. We divided the project into several
different services.
[Web Server (nginx), PHP (php-fpm),
Redis, Mysql (for local development)]
We established an internal repository of base
images using Ansible (and Ansible Container).
We used Docker compose to do the final
configurations and put them all together.
Dockerize The Project

3. CI And Deployment
We used Apache Ant to automate running
tests, run metrics on the code, and build
and push images.
We used multiple build.xml files. One for
each environment (development, Staging,
Production).
We used Bitbucket Pipelines to call the
Ant scripts and deploy.

4. ECS
A container
management service that
supports Docker containers
CloudWatch
a monitoring service for
AWS cloud resources
ELB
Automatically distributes
incoming application traffic
EC2
Secure and
resizable compute
capacity in the cloud.
The Amazon Tools

5. Task Definitions
A set of rules and
configurations for container
instances
AWS CLI
A unified tool to manage
your AWS services
ECR
A fully-managed
Docker container registry
Clusters
a logical grouping
of container instances
Elastic Container Service (ECS)

6. The Flow
New code is
pushed to
Bitbucket.
The pipeline runs the Ant
scripts to build, tag, and
push the docker images.
It also updates the task
definition for the cluster.
Amazon ECS spins up a
new cluster based on the
new task definition.
New users are sent to the
new cluster. The old
cluster falls away as the
existing users fall away.
1 2 3 4

7. Let’s Build An App

8. “We will need to version the API at some point”

9. “OMG !!
We need it versioned NOW!”

10. Versioning Methods (for the client)
Version the URI
http://somesite.com/api/v3/user
A Custom Header
HTTP_API_VERSION: version=3
Content Negotiation
HTTP_ACCEPT:
application/vnd.some-api.v3+json

11. Custom Media Types
Media Type Naming
tree/subtree
i.e. application/json, image/png
Register With IANA:
http://www.iana.org/cgi-bin/
mediatypes.pl
Custom Media Type
vnd.some-api.v3+json

12. Versioning Methods (for the code)
Version in the code
Copy the code
Docker images
based on git tags

13. Versioning In The Code
Constantly adding conditionals in
the code.
Duplicate Code Duplication.
Every version exists in the one code
base.
Possible to accidentally change an
old version.
Ever-increasing code size

14. Copy The Entire Code Base
Duplicate code Duplication.
Possible to accidentally change an
old version.
Ever-increasing code size

15. Versioning With Docker And Git Tags
The repo deals with only one
version at a time
Other versions exist in the history.
Images are stand alone.
Much less likely to change an old
version.
Git is great. Tags are good!

16. OK! But How?
We have decided to use Content
Negotiation and multiple Docker
images, but how do we translate
the the Accept header to the
proper Docker version?

17. Configuring Nginx
The server block
server {
listen 80;
access_log /var/logs/access.log;
error_log /var/logs/error.log;
root /var/www;
location / {
index index.html index.htm index.php;
}
}

18. Configuring Nginx
The server block
server {
listen 80;
access_log /var/logs/access.log;
error_log /var/logs/error.log;
root /var/www;
location / {
index index.html index.htm index.php;
}
location ~ .php$ {
include /etc/nginx/fastcgi_params;
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param $document_root$fastcgi_script_name;
}
}

19. Configuring Nginx
The Upstream block
upstream php {
server unix:/run/php-fpm/php-fpm.sock;
}
server {
listen 80;
…
location ~ .php$ {
include /etc/nginx/fastcgi_params;
fastcgi_pass php;
fastcgi_index index.php;
fastcgi_param $document_root$fastcgi_script_name;
}
}

20. Configuring Nginx
Name Docker Containers
server {
listen 80;
…
location ~ .php$ {
include /etc/nginx/fastcgi_params;
fastcgi_pass php:9000;
fastcgi_index index.php;
fastcgi_param $document_root$fastcgi_script_name;
}
}

21. Configuring Nginx
The Map Directive
map $accept_header $backend {
default ‘php_v1’;
‘application/vnd.some-site.v2+json’ ‘php_v2’;
‘application/vnd.some-site.v3+json’ ‘php_v3’;
}
server {
listen 80;
…
location ~ .php$ {
include /etc/nginx/fastcgi_params;
fastcgi_pass $backend;
fastcgi_index index.php;
fastcgi_param $document_root$fastcgi_script_name;
}
}

22. Configuring Nginx
The Map Directive (with include)
map $accept_header $backend {
default ‘php_v1’;
include /var/version_maps/*
}
server {
listen 80;
…
location ~ .php$ {
include /etc/nginx/fastcgi_params;
fastcgi_pass $backend;
fastcgi_index index.php;
fastcgi_param $document_root$fastcgi_script_name;
}
}

23. Semantic Versioning
Major.Minor.Patch
i.e 3.4.1
Matching The Latest Major
v1 => 1.9.13
v2 => 2.8.7
v3 => 3.4.1
Sockets Don’t Like Dots
unix:/run/php-fpm/php-fpm-v341.sock

24. Configuring Nginx
The Map Directive (with sockets)
map $accept_header $backend {
default ‘unix:/run/php-fpm/php-fpm-v1913.sock’;
‘vnd.some-site.v2’ ‘unix:/run/php-fpm/php-fpm-v287.sock’;
‘vnd.some-site.v3’ ‘unix:/run/php-fpm/php-fpm-v341.sock’;
}
server {
listen 80;
…
location ~ .php$ {
include /etc/nginx/fastcgi_params;
fastcgi_pass $backend;
fastcgi_index index.php;
fastcgi_param $document_root$fastcgi_script_name;
}
}

25. Git Tags And Ant Scripts
Each release gets a version tag in Git.
(And ideally its own branch matching the
minor version).
Update The Ant Build Scripts to pull the Git
tags, loop through them, match major versions
to the LATEST minor/patch version, and create
map files based on this.
Update the php-fpm config to version the
socket.
Update the task definition with the new
tagged image version, and version the
shared socket volume

26. Put It All Together
Tag the code in Git
for release
Ant dynamically builds the
version map files, updates
the task definition and
pushes necessary images.
Amazon ECS spins up a
new Cluster based on the
updated task definition
and tagged images.
nginx uses the Accept
header to map the proper
php-fpm version container.
1 2 3 4

27. Other Concerns - ECS Is Atomic
Atomic! It either all works, or it fails.
There are many pieces to the Amazon
ECS puzzle. Piecing it all together can
sometimes be confusing. And it is easy
to forget something - especially in the
beginning.
Solution: Sadly, trial and error. And the
CloudWatch logs.

28. Other Concerns - The Shared Socket Volume
When we spin up a new “Cluster” the
source volume already exists! This
causes a failure!
Solution: dynamically update the shared
volume on each task definition version.

29. Other Concerns - Memory Limit
The Docker images are basically small
and manageable, but each one takes a
good bit of memory. What happens when
the EC2 instance runs out.
Solution: Amazon has Auto-Scaling
definitions. If properly configured, it will
automagically spin up a new instance.

30. Other Concerns - The Default Map Version
Since we did not have versioning in
the beginning, we had to use the
default (nginx map) as the version 1. So
how do we know if the request is actually
for version 1, or if it asking for a version
that does not exist.
Solution: The dreaded IF statements in
nginx.

31. Apps And API Versioning
Since (for the most part) you cannot
force users to update the app version,
sharing data across multiple versions of
the App can definitely be problematic.
Solution: Preplanning, case by case
solutions, and therapy.

32. Conclusion - It’s Almost Like A Dream

33. Special Thanks Goes To:
Docker
Docker-Compose
Ansible
Ansible Container
Ant
Git
Bitbucket Pipelines
Amazon EC2
Amazon Load Balancer
Amazon ECS
Amazon Auto-Scaling
Amazon CloudWatch
Nginx
Php (fpm)

34. Thank You!