Skip to content

Added a new "Deploying to Heroku Cloud" cookbook article #4045

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
Closed
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 193 additions & 0 deletions cookbook/deployment/heroku.rst
Original file line number Diff line number Diff line change
@@ -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`_
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say "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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

without the comma, it reads easier imo

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Application should be uppercased (it's not a closed class word)

~~~~~~~~~~~~~~~~~~~~~~~~~~

Deploying a Symfony2 application to Heroku doesn't require any change in its
code, but it requires some minor tweaks in its configuration.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"[...] 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would split the first sentence: "[...] directory. This is not ideal [...]"

Heroku, the best way to handle logging is using Logplex, and the best way to
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you should remove the oxford comma before and

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would finish the sentence after "Logplex". And what do you think about adding a link to a page providing some more information about Logplex?

send log data to Logplex is by writing to ``STDERR`` or ``STDOUT``. Luckily
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Luckily, [...]"

Symfony2 uses the excellent Monolog library for logging, and so a new log
destination is just a config file change away.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about something like "[...] library for logging. So, a new log destination is just a change to a config file away."?


Open ``app/config/config_prod.yml`` file, locate ``monolog/handlers/nested``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open the [...] locate the [...]

section and change the value of ``path`` from
``"%kernel.logs_dir%/%kernel.environment%.log"`` to ``"php://stderr"``:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The section isn't necessarily present in the configuration file, is it? So, it might be worth to add a note stating that you can safely add this section if it doesn't exist yet.


.. code-block:: yaml

# app/config/config_prod.yml
monolog:
# ...
handlers:
# ...
nested:
# ...
# path: %kernel.logs_dir%/%kernel.environment%.log
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would just remove this one or change the above text to comment the line and ...

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Application

------------------------------------

To deploy your application to Heroku, you must first create a ``Procfile``,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this really called "Procfile" and not "Profile"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xabbuh I know that Procfile sounds awful, but I've checked it again and it's definitely the correct name in this context :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@javiereguiluz Thanks for clarifying. :)

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you should remove serial comma before and here too

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this note misleading since you already wrote in the list before that the bin dir is bin/?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I should probably reword the text to simplify it. Any suggestions to do it? Thanks!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm ok with this, but we can open a new PR if some better wording comes to us. I kind of like the discussion about how the SE differs from the default.


Create a new file called ``Procfile`` (without any extension) at the root
directory of the application and add just the following content:

.. code-block:: text

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:: 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.
Are you sure you want to continue connecting (yes/no)?

In this case, you need to confirm by typing ``yes`` and hitting ``<Enter>`` 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think bold is needed, it's already happy enough :)

it to the URL ``heroku create`` gave you, or by using the Heroku Toolbelt, the application will respond:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing line break after the word that crosses the 72th character


.. code-block:: bash

$ heroku open
Opening mighty-hamlet-1981... done

*Et voilà!* You should be seeing your Symfony2 application in your browser.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like including french things in an english docs, but others seem to like it so I won't push you to remove it :)


.. _`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
1 change: 1 addition & 0 deletions cookbook/deployment/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,4 @@ Deployment

tools
azure-website
heroku