AWS Elastic Beanstalk
Developer Guide (API Version 2010-12-01)
AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Deploying a Laravel Application to Elastic Beanstalk

Laravel is an open source, model-view-controller (MVC) framework for PHP. This tutorial walks you through the process of generating a Laravel application, deploying it to an AWS Elastic Beanstalk environment, and configuring it to connect to an Amazon Relational Database Service (Amazon RDS) database instance.

Prerequisites

This tutorial assumes that you have some knowledge of basic Elastic Beanstalk operations and the Elastic Beanstalk console. If you haven't already, follow the instructions in Getting Started Using Elastic Beanstalk to launch your first Elastic Beanstalk environment.

To follow the procedures in this guide, you will need a command line terminal or shell to run commands. Commands are shown in listings proceded by a prompt symbol ($) and the name of the current directory, when appropriate:

~/eb-project$ this is a command
this is output

Note

You can run all commands in this tutorial on a Linux virtual machine, OS X, or an Amazon Linux EC2 instance. If you need a development environment, you can launch a single-instance Elastic Beanstalk environment and connect to it with SSH.

Laravel requires PHP 5.5.9 or later and the mbstring extension for PHP. In this tutorial we use PHP 5.6 and the corresponding Elastic Beanstalk platform configuration.

Install PHP 5.6 and the required extensions. Depending on your platform and package manager, the steps will vary.

On Amazon Linux, use yum:

$ sudo yum install php56 --skip-broken
$ sudo yum install php56-mbstring

On OS X, use Homebrew:

$ brew install php56

On Windows, go to the download page at windows.php.net to get PHP, and read the Windows extensions page for information about extensions.

After installing PHP, reopen your terminal and run php --version to ensure that the new version has been installed and is the default.

Install Composer

Composer is a dependency management tool for PHP. It is the preferred tool for installing Laravel and its dependencies and generating a Laravel application.

Install Composer by downloading the installer and running it with PHP. The installer generates a Phar file that you can invoke with PHP to generate a Laravel project n the current directory.

~$ curl -s https://getcomposer.org/installer | php
All settings correct for using Composer
Downloading...

Composer successfully installed to: /home/ec2-user/composer.phar
Use it: php composer.phar

If you run into issues installing Composer, go to the official documentation: https://getcomposer.org/

Install Laravel and Generate a Website

Composer can install Laravel and create a working project with one command:

~$ php composer.phar create-project --prefer-dist laravel/laravel eb-laravel
Installing laravel/laravel (v5.2.15)
  - Installing laravel/laravel (v5.2.15)
    Downloading: 100%

Created project in eb-laravel
> php -r "copy('.env.example', '.env');"
Loading composer repositories with package information
Installing dependencies (including require-dev)
  - Installing vlucas/phpdotenv (v2.2.0)
    Downloading: 100%

  - Installing symfony/polyfill-mbstring (v1.1.0)
    Loading from cache
...

Composer installs Laravel and its dependencies, and generates a default project.

If you run into any issues installing Laravel, go to the installation topic in the official documentation: https://laravel.com/docs/5.2

Create an Elastic Beanstalk Environment and Deploy Your Application

Create a source bundle containing the files created by Composer. You can use any program to create the .zip file, as long as it allows hidden files. On the command line, use the zip command:

~$ cd eb-laravel
~/eb-laravel$ zip ../laravel-default.zip -r * .[^.]*

Save the .zip archive in a location that you can access. This is the source bundle that you will upload to Elastic Beanstalk when you create an environment.

Note

If you are working remotely in an Elastic Beanstalk environment, you can upload the archive to your Elastic Beanstalk storage bucket in Amazon Simple Storage Service (Amazon S3) with the AWS CLI aws cp command:

~$ aws s3 cp laravel-default.zip s3://elasticbeanstalk-us-west-2-123456789012

Elastic Beanstalk creates this bucket the first time you create an environment. To upload files to Amazon S3, you have to give your environment's instance profile permission to write to the bucket.

Use the AWS Management Console to create an Elastic Beanstalk environment running your application. Choose the PHP 5.6 platform configuration and upload your source bundle when prompted:

To launch an environment (console)

  1. Open the Elastic Beanstalk console with this preconfigured link: console.aws.amazon.com/elasticbeanstalk/home#/newApplication?applicationName=tutorials&environmentType=LoadBalanced

  2. For Platform, choose the platform that matches the language used by your application.

  3. For App code, choose Upload.

  4. Choose Local file, choose Browse, and open the source bundle.

  5. Choose Upload.

  6. Choose Review and launch.

  7. Review the available settings and choose Create app.

Environment creation takes about 5 minutes. When the process completes, click the URL to open your Laravel application in the browser:

What's this? By default, Elastic Beanstalk serves the root of your project at the root path of the web site. In this case, though, the default page (index.php) is one level down in the public folder. You can verify this by adding /public to the URL. For example, http://laravel.us-east-1.elasticbeanstalk.com/public.

To allow access to this folder, use the Elastic Beanstalk console to configure the document root for the web site.

To configure your web site's document root

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Configuration.

  4. In the Software Configuration section, choose the settings icon ( Edit ).

  5. For Document Root, type /public.

  6. Choose Apply.

  7. When the update is complete, click the URL to reopen your site in the browser.

So far, so good. Next you'll add a database to your environment and configure Laravel to connect to it.

Add a Database to Your Environment

Launch an RDS DB instance in your Elastic Beanstalk environment. You can use MySQL, SQLServer, or PostgreSQL databases with Laravel on Elastic Beanstalk. For this example, we'll use MySQL.

To add an RDS DB instance to your Elastic Beanstalk environment

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Configuration.

  4. In the Data Tier section, choose create a new RDS database.

  5. For DB engine, choose mysql.

  6. Type a master username and password. Elastic Beanstalk will provide these values to your application using environment properties.

  7. Choose Apply.

Creating a database instance takes about 10 minutes. In the meantime, you can update your source code to read connection information from the environment. Elastic Beanstalk provides connection details using environment variables, such as RDS_HOSTNAME, that you can access from your application.

Laravel's database configuration is stored in a file named database.php in the config folder in your project code. Open this file and add code that reads the environment variables from $_SERVER and assigns them to local variables by inserting the highlighted lines in the following example after the first line (<?php):

Example ~/eb-laravel/config/database.php

<?php
if (!defined('RDS_HOSTNAME')) {
  define('RDS_HOSTNAME', $_SERVER['RDS_HOSTNAME']);
  define('RDS_USERNAME', $_SERVER['RDS_USERNAME']);
  define('RDS_PASSWORD', $_SERVER['RDS_PASSWORD']);
  define('RDS_DB_NAME', $_SERVER['RDS_DB_NAME']);
}
return [
...

The database connection is configured further down in database.php file. Find the following section and modify the default datasources configuration with the name of the driver that matches your database engine (Mysql, Sqlserver, or Postgres), and set the host, database, username, and password variables to read the corresponding values from Elastic Beanstalk:

Example ~/eb-laravel/config/database.php

...
    'connections' => [

        'sqlite' => [
            'driver'   => 'sqlite',
            'database' => database_path('database.sqlite'),
            'prefix'   => '',
        ],

        'mysql' => [
            'driver'    => 'mysql',
            'host'      => RDS_HOSTNAME,
            'database'  => RDS_DB_NAME,
            'username'  => RDS_USERNAME,
            'password'  => RDS_PASSWORD,
            'charset'   => 'utf8',
            'collation' => 'utf8_unicode_ci',
            'prefix'    => '',
            'strict'    => false,
            'engine'    => null,
        ],
...

To verify that the database connection is configured correctly, add code to index.php to connect to the database and add some code to the default response:

Example ~/eb-laravel/public/index.php

...
if(DB::connection()->getDatabaseName())
{
   echo "Connected to database ".DB::connection()->getDatabaseName();
}
$response->send();
...

When the DB instance has finished launching, bundle and deploy the updated application to your environment.

To update your Elastic Beanstalk environment

  1. Create a new source bundle:

    ~/eb-laravel$ zip ../laravel-v2-rds.zip -r * .[^.]*
  2. Open the Elastic Beanstalk console.

  3. Navigate to the management page for your environment.

  4. Choose Upload and Deploy.

  5. Choose Browse, and upload laravel-v2-rds.zip.

  6. Choose Deploy.

Deploying a new version of your application takes less than a minute. When the deployment is complete, refresh the web page again to verify that the database connection succeeded:

Clean Up

When you finish working with Elastic Beanstalk, you can terminate your environment. Elastic Beanstalk terminates all AWS resources associated with your environment, such as Amazon EC2 instances, database instances, load balancers, security groups, and alarms.

To terminate your Elastic Beanstalk environment

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Actions, and then choose Terminate Environment.

  4. In the Confirm Termination dialog box, type the environment name, and then choose Terminate.

In addition, you can terminate database resources that you created outside of your Elastic Beanstalk environment. When you terminate an Amazon RDS database instance, you can take a snapshot and restore the data to another instance later.

To terminate your RDS DB instance

  1. Open the Amazon RDS console.

  2. Choose Instances.

  3. Choose your DB instance.

  4. Choose Instance Actions, and then choose Delete.

  5. Choose whether to create a snapshot, and then choose Delete.

To delete a DynamoDB table

  1. Open the Tables page in the DynamoDB console.

  2. Select a table.

  3. Choose Actions, and then choose Delete table.

  4. Choose Delete.

Next Steps

As you continue to develop your application, you'll probably want a way to manage environments and deploy your application without manually creating a .zip file and uploading it to the Elastic Beanstalk console. The Elastic Beanstalk Command Line Interface (EB CLI) provides easy-to-use commands for creating, configuring, and deploying applications to Elastic Beanstalk environments from the command line.

In this tutorial, you configured a document root for your application. When you launch more environments, it's impractical to manually configure this setting on each environment. You can use configuration files to store this and other settings in your source code, so that they are applied automatically.

Running an RDS DB instance in your Elastic Beanstalk environment is great for development and testing, but it ties the life cycle of your database to your environment. For instructions on connecting to a database running outside of your environment, see Adding an Amazon RDS DB Instance to Your PHP Application Environment .

Finally, if you plan on using your application in a production environment, you will want to configure a custom domain name for your environment and enable HTTPS for secure connections.

For more information about Laravel, go to the tutorial at laravel.com.