This post will show you how can create a Docker Machine instance on AWS (EC2) starting from scratch. This means you're starting with your free AWS account with nothing configured after you have signed up for your free AWS trial account.

To create a Docker machine instance in AWS, the docker-machine command requires several params for the AWS driver.

At a minimum, we need to provide these params:

• amazonec2-access-key
• amazonec2-secret-key
• amazonec2-region
• amazonec2-zone
• amazonec2-vpc-id

To get the amazonec2-access-key and the amazonec2-secret-key we need to have an Amazon EC2 Access Key and an Amazon EC2 Secret Key.

Both of them can be obtained by creating a user in IAM.

Clicking on the "Create New Users" button will bring up this view where we create a new user named "awsdockeruser":

Make sure to check "Generate an access key for each user".

After creating the user, we'll get both keys:

Make sure to create a copy at safe place as this is the last time you'll see them in IAM.

In order to manage AWS EC2 instances we need the appropriate permissions. To assign the permission to manage EC2 instances our awsdockeruser needs to be a member of a group which has that permission.

So lets create that group in the IAM dashboard:

We'll called it "awsdockergroup"

Next, assign the policy to manage EC2 instances (there might be lower privileges that are sufficient):

Next, lets add the "awsdockeruser" to our group:

Next, we need to know region, zone and VPC id. These can be obtained by using the AWS CLI.

On Linux and OS X, it can be installed using PIP package manager.

pip install awscli

Then AWS CLI needs to be configured:

aws configure

AWS CLI configurations asks you for your AWS Access Key ID, your AWS Secret Access Key (remember them? 😀), Default region name (codes can be found here - I've choosen eu-central-1), and Default output format which I set to json.

To get the vpc-id, just run:

aws ec2 describe-subnets

The output will look like this:

{
    "Subnets": [
        {
            "VpcId": "<avpcid>",
            "CidrBlock": "172.31.0.0/20",
            "MapPublicIpOnLaunch": true,
            "DefaultForAz": true,
            "State": "available",
            "AvailabilityZone": "eu-central-1a",
            "SubnetId": "<asubnetid>",
            "AvailableIpAddressCount": 4091
        },
        {
            "VpcId": "<anothervpcid>",
            "CidrBlock": "172.31.16.0/20",
            "MapPublicIpOnLaunch": true,
            "DefaultForAz": true,
            "State": "available",
            "AvailabilityZone": "eu-central-1b",
            "SubnetId": "<anothersubnetid>",
            "AvailableIpAddressCount": 4091
        }
    ]
}

The amazonec2-zone param is the last character of the AvailabilityZone of the subnet you choose to use, so a or b here.

Ok, it's time to spin up our Docker machine instance...

docker-machine create \ 
				-d amazonec2 \
				--amazonec2-access-key <YOURACCESSKEY> \
				--amazonec2-secret-key <YOURSECRETKEY> \
				--amazonec2-zone a \
				--amazonec2-region eu-central-1 \
				--amazonec2-vpc-id <YOURVPCID> 
				awsdocker

After about 60 seconds, your console should confirm your machine is ready to rock'n roll

Launching instance...
To see how to connect Docker to this machine, run: docker-machine env awsdocker

To connect to the machine, run this command:

eval $(docker-machine env awsdocker)

To make sure everything works as expected, just run docker ps.

If you're working with various machines, you might want to know which is your current active machine:

You can have this in your prompt if you use my bash prompt definiton from here.

Using docker-machine ip awsdocker you can get the public IP address of your machine.

If you're deploying some containers, you might wonder, why you can`t access your containers exposed ports like http://<machine-ip>:<someport>: because firewall 😱.

So head over to the EC2 dashboard "Security Groups" section, select your "docker-machine" Security Group (which has been created when spinning up your machine) and make sure to allow some inbound traffic:

Happy shipping! 😀