From 51520e5789bb34415631b968663be1c145bd0362 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Jul 2014 15:38:46 +0200 Subject: [PATCH 1/6] First draft of "Deploying to Heroku Cloud" cookbook article --- cookbook/deployment/heroku.rst | 193 +++++++++++++++++++++++++++++++++ cookbook/deployment/index.rst | 1 + 2 files changed, 194 insertions(+) create mode 100644 cookbook/deployment/heroku.rst diff --git a/cookbook/deployment/heroku.rst b/cookbook/deployment/heroku.rst new file mode 100644 index 00000000000..06c4cd50f01 --- /dev/null +++ b/cookbook/deployment/heroku.rst @@ -0,0 +1,193 @@ +.. index:: + single: Deployment; Deploying to Heroku Cloud + +Deploying to Heroku Cloud +========================= + +This step by step cookbook describes how to deploy a Symfony2 web application to +the Heroku cloud platform. Its contents are based on `this original article`_ +published by Heroku. + +Setting up +---------- + +To setup a new Heroku website, first `signup with Heroku`_ or sign in +with your credentials. Then, download and install the `Heroku Toolbet`_ on your +local computer. + +You can also check out the `getting Started with PHP on Heroku`_ guide to gain +more familiarity with the specifics of working with PHP applications on Heroku. + +Preparing your application +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Deploying a Symfony2 application to Heroku doesn't require any change in its +code, but it requires some minor tweaks in its configuration. + +By default, the Symfony2 app will log into your application's ``app/log/`` +directory, which isn't ideal as Heroku uses an `ephemeral file system`_. On +Heroku, the best way to handle logging is using Logplex, and the best way to +send log data to Logplex is by writing to ``STDERR`` or ``STDOUT``. Luckily +Symfony2 uses the excellent Monolog library for logging, and so a new log +destination is just a config file change away. + +Open ``app/config/config_prod.yml`` file, locate ``monolog/handlers/nested`` +section and change the value of ``path`` from +``"%kernel.logs_dir%/%kernel.environment%.log"`` to ``"php://stderr"``: + +.. code-block:: yaml + + # app/config/config_prod.yml + monolog: + # ... + handlers: + # ... + nested: + # ... + # path: %kernel.logs_dir%/%kernel.environment%.log + path: "php://stderr" + +Once the application is deployed, run ``heroku logs --tail`` to keep the +stream of logs from Heroku open in your terminal. + +Creating a new application on Heroku +------------------------------------ + +To create a new Heroku application that you can push to, use the CLI ``create`` +command: + +.. code-block:: bash + + $ heroku create + + Creating mighty-hamlet-1981 in organization heroku... done, stack is cedar + http://mighty-hamlet-1981.herokuapp.com/ | git@heroku.com:mighty-hamlet-1981.git + Git remote heroku added + +You are now ready to deploy the application as explained in the next section. + +Deploying your application on Heroku +------------------------------------ + +To deploy your application to Heroku, you must first create a ``Procfile``, +which tells Heroku what command to use to launch the web server with the +correct settings. After you've done that, you can simply ``git push``, and +you're done! + +Creating a Procfile +~~~~~~~~~~~~~~~~~~~ + +By default, Heroku will launch an Apache web server together with PHP to serve +applications. However, two special circumstances apply to Symfony applications: + +1. The document root is in the ``web/`` directory and not in the root directory + of the application; +2. The Composer ``bin-dir``, where vendor binaries (and thus Heroku's own boot + scripts) are placed, is ``bin/`` , and not the default ``vendor/bin``. + +.. note:: + + Vendor binaries are usually installed to ``vendor/bin`` by Composer, but + sometimes (e.g. when running a Symfony Standard Edition project!), the + location will be different. If in doubt, you can always run + ``composer config bin-dir`` to figure out the right location. + +Create a new file called ``Procfile`` (without any extension) at the root +directory of the application and add just the following content: + +.. code-block:: + + web: bin/heroku-php-apache2 web/ + +If you prefer working on the command console, execute the following commands to +create the ``Procfile`` file and to add it to the repository: + +.. code-block:: bash + + $ echo "web: bin/heroku-php-apache2 web/" > Procfile + $ git add . + $ git commit -m "Procfile for Apache and PHP" + [master 35075db] Procfile for Apache and PHP + 1 file changed, 1 insertion(+) + +Pushing to Heroku +~~~~~~~~~~~~~~~~~ + +Next up, it's finally time to deploy your application to Heroku. If you are +doing this for the very first time, you may see a message such as the following: + +.. code-block: + + The authenticity of host 'heroku.com (50.19.85.132)' can't be established. + RSA key fingerprint is 8b:48:5e:67:0e:c9:16:47:32:f2:87:0c:1f:c8:60:ad. + Are you sure you want to continue connecting (yes/no)? + +In this case, you need to confirm by typing ``yes`` and hitting ```` key +- ideally after you've `verified that the RSA key fingerprint is correct`_. + +Then, deploy your application executing this command: + +.. code-block:: bash + + $ git push heroku master + + Initializing repository, done. + Counting objects: 130, done. + Delta compression using up to 4 threads. + Compressing objects: 100% (107/107), done. + Writing objects: 100% (130/130), 70.88 KiB | 0 bytes/s, done. + Total 130 (delta 17), reused 0 (delta 0) + + -----> PHP app detected + + -----> Setting up runtime environment... + - PHP 5.5.12 + - Apache 2.4.9 + - Nginx 1.4.6 + + -----> Installing PHP extensions: + - opcache (automatic; bundled, using 'ext-opcache.ini') + + -----> Installing dependencies... + Composer version 64ac32fca9e64eb38e50abfadc6eb6f2d0470039 2014-05-24 20:57:50 + Loading composer repositories with package information + Installing dependencies from lock file + - ... + + Generating optimized autoload files + Creating the "app/config/parameters.yml" file + Clearing the cache for the dev environment with debug true + Installing assets using the hard copy option + Installing assets for Symfony\Bundle\FrameworkBundle into web/bundles/framework + Installing assets for Acme\DemoBundle into web/bundles/acmedemo + Installing assets for Sensio\Bundle\DistributionBundle into web/bundles/sensiodistribution + + -----> Building runtime environment... + + -----> Discovering process types + Procfile declares types -> web + + -----> Compressing... done, 61.5MB + + -----> Launching... done, v3 + http://mighty-hamlet-1981.herokuapp.com/ deployed to Heroku + + To git@heroku.com:mighty-hamlet-1981.git + * [new branch] master -> master + +**And that's it!** If you now open your browser, either by manually pointing +it to the URL ``heroku create`` gave you, or by using the Heroku Toolbelt, the application will respond: + +.. code-block:: bash + + $ heroku open + Opening mighty-hamlet-1981... done + +*Et voilà!* You should be seeing your Symfony2 application in your browser. + +.. _`this original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2 +.. _`signup with Heroku`: https://signup.heroku.com/signup/dc +.. _`Heroku Toolbet`: https://devcenter.heroku.com/articles/getting-started-with-php#local-workstation-setup +.. _`getting Started with PHP on Heroku`: .. _`Heroku Toolbet`: https://devcenter.heroku.com/articles/getting-started-with-php +.. _`ephemeral file system`: https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem +.. _`verified that the RSA key fingerprint is correct`: https://devcenter.heroku.com/articles/git-repository-ssh-fingerprints diff --git a/cookbook/deployment/index.rst b/cookbook/deployment/index.rst index fb454401a24..ef5699e8cea 100644 --- a/cookbook/deployment/index.rst +++ b/cookbook/deployment/index.rst @@ -6,3 +6,4 @@ Deployment tools azure-website + heroku From 2c9194ae3d163e95540d6c47ef1e22aba54ecd6b Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Jul 2014 16:00:33 +0200 Subject: [PATCH 2/6] Fixed som RST syntax errors --- cookbook/deployment/heroku.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/deployment/heroku.rst b/cookbook/deployment/heroku.rst index 06c4cd50f01..0ee0a6625e1 100644 --- a/cookbook/deployment/heroku.rst +++ b/cookbook/deployment/heroku.rst @@ -95,7 +95,7 @@ applications. However, two special circumstances apply to Symfony applications: Create a new file called ``Procfile`` (without any extension) at the root directory of the application and add just the following content: -.. code-block:: +.. code-block:: text web: bin/heroku-php-apache2 web/ @@ -116,7 +116,7 @@ Pushing to Heroku Next up, it's finally time to deploy your application to Heroku. If you are doing this for the very first time, you may see a message such as the following: -.. code-block: +.. code-block:: bash The authenticity of host 'heroku.com (50.19.85.132)' can't be established. RSA key fingerprint is 8b:48:5e:67:0e:c9:16:47:32:f2:87:0c:1f:c8:60:ad. From 11981a87d4e63e3b74cdd5f5f5397a0a9d6c81e6 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Jul 2014 22:39:58 +0200 Subject: [PATCH 3/6] Added the new cookbook to the article map --- cookbook/map.rst.inc | 1 + 1 file changed, 1 insertion(+) diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index c2ec20632e5..5399f3f637e 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -51,6 +51,7 @@ * :doc:`/cookbook/deployment/tools` * :doc:`/cookbook/deployment/azure-website` + * :doc:`/cookbook/deployment/heroku` * :doc:`/cookbook/doctrine/index` From 29641a2561da7a4b5b11afe289609ab8850faddb Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Jul 2014 22:44:57 +0200 Subject: [PATCH 4/6] Fixed all problems reported by @WouterJ --- cookbook/deployment/heroku.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/cookbook/deployment/heroku.rst b/cookbook/deployment/heroku.rst index 0ee0a6625e1..1607cb0efc1 100644 --- a/cookbook/deployment/heroku.rst +++ b/cookbook/deployment/heroku.rst @@ -5,20 +5,20 @@ Deploying to Heroku Cloud ========================= This step by step cookbook describes how to deploy a Symfony2 web application to -the Heroku cloud platform. Its contents are based on `this original article`_ +the Heroku cloud platform. Its contents are based on `the original article`_ published by Heroku. Setting up ---------- To setup a new Heroku website, first `signup with Heroku`_ or sign in -with your credentials. Then, download and install the `Heroku Toolbet`_ on your +with your credentials. Then download and install the `Heroku Toolbet`_ on your local computer. You can also check out the `getting Started with PHP on Heroku`_ guide to gain more familiarity with the specifics of working with PHP applications on Heroku. -Preparing your application +Preparing your Application ~~~~~~~~~~~~~~~~~~~~~~~~~~ Deploying a Symfony2 application to Heroku doesn't require any change in its @@ -28,7 +28,7 @@ By default, the Symfony2 app will log into your application's ``app/log/`` directory, which isn't ideal as Heroku uses an `ephemeral file system`_. On Heroku, the best way to handle logging is using Logplex, and the best way to send log data to Logplex is by writing to ``STDERR`` or ``STDOUT``. Luckily -Symfony2 uses the excellent Monolog library for logging, and so a new log +Symfony2 uses the excellent Monolog library for logging and so a new log destination is just a config file change away. Open ``app/config/config_prod.yml`` file, locate ``monolog/handlers/nested`` @@ -44,13 +44,12 @@ section and change the value of ``path`` from # ... nested: # ... - # path: %kernel.logs_dir%/%kernel.environment%.log path: "php://stderr" Once the application is deployed, run ``heroku logs --tail`` to keep the stream of logs from Heroku open in your terminal. -Creating a new application on Heroku +Creating a New Application on Heroku ------------------------------------ To create a new Heroku application that you can push to, use the CLI ``create`` @@ -66,12 +65,12 @@ command: You are now ready to deploy the application as explained in the next section. -Deploying your application on Heroku +Deploying your Application on Heroku ------------------------------------ To deploy your application to Heroku, you must first create a ``Procfile``, which tells Heroku what command to use to launch the web server with the -correct settings. After you've done that, you can simply ``git push``, and +correct settings. After you've done that, you can simply ``git push`` and you're done! Creating a Procfile @@ -175,15 +174,16 @@ Then, deploy your application executing this command: To git@heroku.com:mighty-hamlet-1981.git * [new branch] master -> master -**And that's it!** If you now open your browser, either by manually pointing -it to the URL ``heroku create`` gave you, or by using the Heroku Toolbelt, the application will respond: +And that's it! If you now open your browser, either by manually pointing +it to the URL ``heroku create`` gave you, or by using the Heroku Toolbelt, the +application will respond: .. code-block:: bash $ heroku open Opening mighty-hamlet-1981... done -*Et voilà!* You should be seeing your Symfony2 application in your browser. +You should be seeing your Symfony2 application in your browser. .. _`this original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2 .. _`signup with Heroku`: https://signup.heroku.com/signup/dc From a70d2e06227453080bb8dad4c2867a841a411620 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Jul 2014 22:56:05 +0200 Subject: [PATCH 5/6] Fixed the target of one link --- cookbook/deployment/heroku.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/deployment/heroku.rst b/cookbook/deployment/heroku.rst index 1607cb0efc1..df41a8ce874 100644 --- a/cookbook/deployment/heroku.rst +++ b/cookbook/deployment/heroku.rst @@ -185,7 +185,7 @@ application will respond: You should be seeing your Symfony2 application in your browser. -.. _`this original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2 +.. _`the original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2 .. _`signup with Heroku`: https://signup.heroku.com/signup/dc .. _`Heroku Toolbet`: https://devcenter.heroku.com/articles/getting-started-with-php#local-workstation-setup .. _`getting Started with PHP on Heroku`: .. _`Heroku Toolbet`: https://devcenter.heroku.com/articles/getting-started-with-php From 6a0a7d38cebb0c3edb487f35af85570379f5de55 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 25 Jul 2014 08:33:13 +0200 Subject: [PATCH 6/6] Applied all the fixes suggested by @xabbuh --- cookbook/deployment/heroku.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/cookbook/deployment/heroku.rst b/cookbook/deployment/heroku.rst index df41a8ce874..42a79292f13 100644 --- a/cookbook/deployment/heroku.rst +++ b/cookbook/deployment/heroku.rst @@ -22,17 +22,18 @@ Preparing your Application ~~~~~~~~~~~~~~~~~~~~~~~~~~ Deploying a Symfony2 application to Heroku doesn't require any change in its -code, but it requires some minor tweaks in its configuration. +code, but it requires some minor tweaks to its configuration. By default, the Symfony2 app will log into your application's ``app/log/`` -directory, which isn't ideal as Heroku uses an `ephemeral file system`_. On -Heroku, the best way to handle logging is using Logplex, and the best way to -send log data to Logplex is by writing to ``STDERR`` or ``STDOUT``. Luckily -Symfony2 uses the excellent Monolog library for logging and so a new log -destination is just a config file change away. - -Open ``app/config/config_prod.yml`` file, locate ``monolog/handlers/nested`` -section and change the value of ``path`` from +directory. This is not ideal as Heroku uses an `ephemeral file system`_. On +Heroku, the best way to handle logging is using `Logplex`_. And the best way to +send log data to Logplex is by writing to ``STDERR`` or ``STDOUT``. Luckily, +Symfony2 uses the excellent Monolog library for logging. So, a new log +destination is just a change to a config file away. + +Open the ``app/config/config_prod.yml`` file, locate the +``monolog/handlers/nested`` section (or create it if it doesn't exist yet) and +change the value of ``path`` from ``"%kernel.logs_dir%/%kernel.environment%.log"`` to ``"php://stderr"``: .. code-block:: yaml @@ -49,7 +50,7 @@ section and change the value of ``path`` from Once the application is deployed, run ``heroku logs --tail`` to keep the stream of logs from Heroku open in your terminal. -Creating a New Application on Heroku +Creating a new Application on Heroku ------------------------------------ To create a new Heroku application that you can push to, use the CLI ``create`` @@ -190,4 +191,5 @@ You should be seeing your Symfony2 application in your browser. .. _`Heroku Toolbet`: https://devcenter.heroku.com/articles/getting-started-with-php#local-workstation-setup .. _`getting Started with PHP on Heroku`: .. _`Heroku Toolbet`: https://devcenter.heroku.com/articles/getting-started-with-php .. _`ephemeral file system`: https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem +.. _`Logplex`: https://devcenter.heroku.com/articles/logplex .. _`verified that the RSA key fingerprint is correct`: https://devcenter.heroku.com/articles/git-repository-ssh-fingerprints