Skip to content

Commit bcd62ae

Browse files
committed
feature #5088 [Cookbook] Custom compile steps on Heroku (bicpi)
This PR was merged into the 2.3 branch. Discussion ---------- [Cookbook] Custom compile steps on Heroku | Q | A | ------------- | --- | Doc fix? | no | New docs? | no | Applies to | all | Fixed tickets | #4217 (partially, list item 3) Commits ------- cb71ad0 [Cookbook] Custom compile steps on Heroku
2 parents a2902f4 + cb71ad0 commit bcd62ae

File tree

1 file changed

+85
-0
lines changed

1 file changed

+85
-0
lines changed

cookbook/deployment/heroku.rst

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,85 @@ You should be seeing your Symfony application in your browser.
235235
AcmeDemoBundle is only loaded in the dev environment (check out your
236236
``AppKernel`` class). Try opening ``/app/example`` from the AppBundle.
237237

238+
Custom Compile Steps
239+
~~~~~~~~~~~~~~~~~~~~
240+
241+
If you wish to execute additional custom commands during a build, you can leverage
242+
Heroku's `custom compile steps`_. Imagine you want to remove the ``dev`` front controller
243+
from your production environment on Heroku in order to avoid a potential vulnerability.
244+
Adding a command to remove ``web/app_dev.php`` to Composer's `post-install-commands`_ would
245+
work, but it also removes the controller in your local development environment on each
246+
``composer install`` or ``composer update`` respectively. Instead, you can add a
247+
`custom Composer command`_ named ``compile`` (this key name is a Heroku convention) to the
248+
``scripts`` section of your ``composer.json``. The listed commands hook into Heroku's deploy
249+
process:
250+
251+
.. code-block:: json
252+
253+
{
254+
"scripts": {
255+
"compile": [
256+
"rm web/app_dev.php"
257+
]
258+
}
259+
}
260+
261+
This is also very useful to build assets on the production system, e.g. with Assetic:
262+
263+
.. code-block:: json
264+
265+
{
266+
"scripts": {
267+
"compile": [
268+
"app/console assetic:dump"
269+
]
270+
}
271+
}
272+
273+
.. sidebar:: Node.js Dependencies
274+
275+
Building assets may depend on node packages, e.g. ``uglifyjs`` or ``uglifycss``
276+
for asset minification. Installing node packages during the deploy requires a node
277+
installation. But currently, Heroku compiles your app using the PHP buildpack, which
278+
is auto-detected by the presence of a ``composer.json`` file, and does not include a
279+
node installation. Because the Node.js buildpack has a higher precedence than the PHP
280+
buildpack (see `Heroku buildpacks`_), adding a ``package.json`` listing your node
281+
dependencies makes Heroku opt for the Node.js buildpack instead:
282+
283+
.. code-block:: json
284+
285+
{
286+
"name": "myApp",
287+
"engines": {
288+
"node": "0.12.x"
289+
},
290+
"dependencies": {
291+
"uglifycss": "*",
292+
"uglify-js": "*"
293+
}
294+
}
295+
296+
With the next deploy, Heroku compiles your app using the Node.js buildpack and
297+
your npm packages become installed. On the other hand, your ``composer.json`` is
298+
now ignored. To compile your app with both buildpacks, Node.js *and* PHP, you can
299+
use a special `multiple buildpack`_. To override buildpack auto-detection, you
300+
need to explicitly set the buildpack URL:
301+
302+
.. code-block:: bash
303+
304+
$ heroku buildpack:set https://github.com/ddollar/heroku-buildpack-multi.git
305+
306+
Next, add a ``.buildpacks`` file to your project, listing the buildpacks you need:
307+
308+
.. code-block:: text
309+
310+
https://github.com/heroku/heroku-buildpack-nodejs.git
311+
https://github.com/heroku/heroku-buildpack-php.git
312+
313+
With the next deploy, you can benefit from both buildpacks. This setup also enables
314+
your Heroku environment to make use of node based automatic build tools like
315+
`Grunt`_ or `gulp`_.
316+
238317
.. _`the original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2
239318
.. _`signup with Heroku`: https://signup.heroku.com/signup/dc
240319
.. _`Heroku Toolbelt`: https://devcenter.heroku.com/articles/getting-started-with-php#local-workstation-setup
@@ -244,3 +323,9 @@ You should be seeing your Symfony application in your browser.
244323
.. _`verified that the RSA key fingerprint is correct`: https://devcenter.heroku.com/articles/git-repository-ssh-fingerprints
245324
.. _`post-install-commands`: https://getcomposer.org/doc/articles/scripts.md
246325
.. _`config vars`: https://devcenter.heroku.com/articles/config-vars
326+
.. _`custom compile steps`: https://devcenter.heroku.com/articles/php-support#custom-compile-step
327+
.. _`custom Composer command`: https://getcomposer.org/doc/articles/scripts.md#writing-custom-commands
328+
.. _`Heroku buildpacks`: https://devcenter.heroku.com/articles/buildpacks
329+
.. _`multiple buildpack`: https://github.com/ddollar/heroku-buildpack-multi.git
330+
.. _`Grunt`: http://gruntjs.com
331+
.. _`gulp`: http://gulpjs.com

0 commit comments

Comments
 (0)