Deploy with AWS CodeDeploy and BitBucket

by   AWS Laravel

Friday, 15 July 2016

Link to Github repo

CodeDeploy is an Amazon Web Services (AWS) service to help coordinate your application deployment to EC2 instances. You don't need to go through FTP applications anymore to push code into your app. You do it directly from your version control system (VCS). Integrating CodeDeploy with Github is pretty well-documented online, with videos and step by step instructions. But what if you prefer working with BitBucket? If you're anything like me, you truly appreciate disposing of unlimited private repos for free - a service that only BitBucket offers. Luckily, there are also great online resources to help using this service with BitBucket. However, one key point that is not made clear enouph from the aforementionned documentation - or at least it isn't to me - is that you need to launch your instance with proper policies attached to your IAM role. So, in this post, we are going to review the entire process of deploying an application to a virtual web server with BitBucket. And hopefully, this will work like a breeze!


  • You'll need to have a valid AWS account to follow along. Remember, once you've registered, you get one year of free access to AWS resources. Click here to start.
  • You'll need a BitBucket account. Click here to register.

I have prepared a basic CloudFormation stack for you to use. It consists of a single Ubuntu EC2 instance attached to a security group with an IAM role. Here's the architecture:


And here is the related JSON code. As you can see, it comes pre-configured with Nginx and PHP, as well as the AWS CodeDeploy Agent. So go ahead, open up CloudFormation in your AWS console, create a new stack and enter the above-mentioned JSON code link address under the "Specify an Amazon S3 template URL" field. Specify a stack's name, a name for the project and your EC2 KeyPair (in case you haven't created such a KeyPair so far, visit this page). Click "Next", optionally providing instance tags, and finally "Create". To make sure it all works out, once the stack has finished installing, open the outputs tag and click the link to visit the homepage. You should see the Nginx web server 404 message:


Despite all appearances, this is good news, as it states our webserver is correctly installed. We are going to add content next! But before that, make also sure the agent is properly installed by typing the following command in your CLI, after you've successfully connected to your instance:

sudo service codedeploy-agent status

You should get a message like "The AWS CodeDeploy agent is running at PID XXXX". In case there's something wrong with the agent, try reinstalling it following these instructions.


Now that we have all the pre-defined AWS elements in place, there are a couple of operations you'll need to do in order to succeed in your code deployment. They will take place in both the AWS Console and your CLI. Let's review them.

Create new AWS role

First, in your AWS console, enter the IAM Service and create a new role that you'll use for your CodeDeploy application. Name it "CodeDeployServiceRole", select "AWS CodeDeploy" as an AWS Service Role and attach it the "AWSCodeDeployRole" policy.

Create new BitBucket repo

A BitBucket repo will serve as a base for our future deployment. Create a new empty repo in your BitBucket account. Call it "codeDeploy" for example. Initialize a new Git repository and commit and push the contributors.txt file as specified in the "I'm starting from scratch" pulldown menu.

Install CodeDeploy add-on

Now that you have a repo with a single file (contributors.txt), let's install the CodeDeploy add-on through the settings menu:

codeDeploy add-on

Follow the provided instructions on how to configure your add-on. It basically consists of creating a new policy and attach it to a specific role in order to provide relevant permissions to the add-on. You'll have to provide the ARN identifier of the new role as well as your AWS Region. Save this new configuration.

codeDeploy add-on

Create the appspec.yml file

There remains to create the appspec.yml file, which defines the modalities of your application deployment. It is located in your app folder, alongside the contributors text file and contains the following YAML code lines.


version: 0.0
os: linux
  - source: /
    destination: /var/www/laravel/

Here, we simply state that we want to deploy the code from the repo root folder of our project to the distant Laravel folder (which is hopefully empty for now. Note that the first deployment will not work if the distant folder already contains files).

Install Laravel locally

Always in your local codeDeploy folder, install the latest version of Laravel composer create-project --prefer-dist laravel/laravel It should now run locally.

Laravel local

Commit and push these changes to BitBucket. Now we want to reflect this local system to the distant web server.

Deploy your app

Back to your AWS console, head over to the CodeDeploy service to create a new application. Make sure you choose an application name that matches your instance name ("codeDeploy" in this case). Pick up also a relevant deployment group name ("codeDeploy_Group" for example). Select your running EC2 instance and as a service role, select the "CodeDeployServiceRole" we created in the first step. You're now ready to deploy your local files. In your BitBucket repo, click on the commit you want to see deployed and then go on by clicking "Deploy to AWS".

deploy to aws button

Once the deployment is successful, notice that the vendor package is not part of the transfer, so you'll have to install dependencies in your distant Laravel folder (path: /var/www/laravel):

sudo composer install

Also, change ownership:

sudo chown -R :www-data /var/www/laravel

Change permissions:

sudo chmod -R 775 /var/www/laravel/storage

Create default .env file:

sudo mv .env.example .env

Finally, generate application key:

sudo php artisan key:generate

End Result

Visit the public DNS of your EC2 instance:

Laravel distant

Make a quick change to your app. For example, add a background color to the welcome page on line 20.


body {
    background: orange;

Then commit and push this change. In your BitBucket repo, select this new commit and click "Deploy to AWS".

Laravel distant new background color

There you have it: In just 2 clicks, you were able to deploy any change in your app to your live instance!

Blog Search


Hi there! My name is Jean-Marc Kleger and I'm a web developer. Welcome to my blog where a share some tips on how to deal with a selection of challenges encountered in my day-to-day coding workflow. Most articles are related to their own Github repo so that you can quickly experiment the code. Don't hesitate also to make use of the comment section at the end of each post to share your knowledge on the topic. Enjoy the visit!