From 2a7d2736f4350e430821eef2f92a026338959a44 Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Thu, 4 Oct 2012 15:21:28 -0500 Subject: [PATCH 1/8] add cookbook for deployment tools --- cookbook/deployment-tools.rst | 73 +++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 cookbook/deployment-tools.rst diff --git a/cookbook/deployment-tools.rst b/cookbook/deployment-tools.rst new file mode 100644 index 00000000000..bcda90ab96b --- /dev/null +++ b/cookbook/deployment-tools.rst @@ -0,0 +1,73 @@ +.. index:: + single: Deployment Tools + +How to deploy a symfony2 application +==================================== + +There are several ways you can deploy a symfony2 application: + +* One way is moving the files manually or via ftp if you don't use versioning + (e.g. git). + +* If you use versioning you could still move things manually cloning or fetching + your repository from the final server folder location. However it is advised + you make use of better tools especially in the case where you have access + capabilities such as enough permissions in a virtual private server or similar system. + +* Some projects are really large so they make use of more established tools for + deploying not only the files but really deploy a OS or package distribution + containing the sf2 project inside. + +* Another important thing to keep in mind is the handling of dependencies. + One can use composer to fetch dependencies or include them all together with the + repository. Some tools would handle this for you and even perhaps avoid fetching + dependencies when a simple copy would do. + +* Remember deployment process includes all the setup and configuring, warming up caches, + cleaning cache, all configuring environment required, setting of permissions, run of + cron jobs, etc. All these before, during and after the deployment should be kept in + mind to properly deploy a working symfony2 application. + +Deployment of large applications require care. The use of staging, testing, QA, +continuous integration, database migrations and capability to roll back in case of failure +is strongly advised. There are simple and more complex tools and one can make +the deployment as easy or sophisticated. Here we present only a few popular on the map: + +The Tools +--------- + +`Capifony`_: + + This tool is a deployment recipe on top of capistrano for symfony2 project + +`Magallanes`_: + + This tool is probably the one top php deployment tool capistrano-like for deploying any kind of php project + +`sf2debpkg`_: + + This tool helps you build a native debian package for your symfony project + +Bundles: + + There are `listings`_ of bundles for deployment you can search and use + +Basic scripting: + + You can of course use shell, `ant`_, or other build tool to script the deploying of your project + +Deployment services: + + Some services require a single file in project's git repository like `pagodabox`_ to handle all deployment + + +.. tip:: + + Consult your symfony community at IRC channel #symfony2 for more fresh ideas or common problems. + +.. _`Capifony`: https://capifony.org/ +.. _`sf2debpkg`: https://github.com/liip/sf2debpkg +.. _`ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant +.. _`pagodabox`: https://github.com/jmather/pagoda-symfony-sonata-distribution/blob/master/Boxfile +.. _`Magallanes`: https://github.com/andres-montanez/Magallanes +.. _`listings`: http://knpbundles.com/search?q=deploy \ No newline at end of file From 9250895a6a1b022e8af2ea0fc8ccb6b7464fc50d Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Thu, 4 Oct 2012 15:23:30 -0500 Subject: [PATCH 2/8] add entries to index and map files --- cookbook/index.rst | 1 + cookbook/map.rst.inc | 2 ++ 2 files changed, 3 insertions(+) diff --git a/cookbook/index.rst b/cookbook/index.rst index d74b85459c5..b2e6f87de0f 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -27,5 +27,6 @@ The Cookbook profiler/index web_services/index symfony1 + deployment-tools .. include:: /cookbook/map.rst.inc diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 77b79823d32..f02aeabd6e8 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -145,3 +145,5 @@ * :doc:`/cookbook/workflow/new_project_git` * :doc:`/cookbook/workflow/new_project_svn` + +* :doc:`/cookbook/deployment-tools/index` \ No newline at end of file From 77c9d00ed08d3089b7ab2db65cb77d7cd76b8cec Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Fri, 5 Oct 2012 21:00:49 -0500 Subject: [PATCH 3/8] address comments --- cookbook/deployment-tools.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/deployment-tools.rst b/cookbook/deployment-tools.rst index bcda90ab96b..54dd64c3aea 100644 --- a/cookbook/deployment-tools.rst +++ b/cookbook/deployment-tools.rst @@ -7,21 +7,21 @@ How to deploy a symfony2 application There are several ways you can deploy a symfony2 application: * One way is moving the files manually or via ftp if you don't use versioning - (e.g. git). + (e.g. git); * If you use versioning you could still move things manually cloning or fetching your repository from the final server folder location. However it is advised you make use of better tools especially in the case where you have access - capabilities such as enough permissions in a virtual private server or similar system. + capabilities such as enough permissions in a virtual private server or similar system; * Some projects are really large so they make use of more established tools for deploying not only the files but really deploy a OS or package distribution - containing the sf2 project inside. + containing the sf2 project inside; * Another important thing to keep in mind is the handling of dependencies. One can use composer to fetch dependencies or include them all together with the repository. Some tools would handle this for you and even perhaps avoid fetching - dependencies when a simple copy would do. + dependencies when a simple copy would do; * Remember deployment process includes all the setup and configuring, warming up caches, cleaning cache, all configuring environment required, setting of permissions, run of From 19e4aa2e50b99ec96a657a7101978af4890c05df Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Fri, 5 Oct 2012 21:12:11 -0500 Subject: [PATCH 4/8] address first set of jmather comments --- cookbook/deployment-tools.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/deployment-tools.rst b/cookbook/deployment-tools.rst index 54dd64c3aea..605c139d9b5 100644 --- a/cookbook/deployment-tools.rst +++ b/cookbook/deployment-tools.rst @@ -23,8 +23,8 @@ There are several ways you can deploy a symfony2 application: repository. Some tools would handle this for you and even perhaps avoid fetching dependencies when a simple copy would do; -* Remember deployment process includes all the setup and configuring, warming up caches, - cleaning cache, all configuring environment required, setting of permissions, run of +* Do remember that deployment process includes all the setup and configuring, warming up caches, + cleaning cache, all configuration environment required, setting of permissions, run of cron jobs, etc. All these before, during and after the deployment should be kept in mind to properly deploy a working symfony2 application. From e6000a7fc661c61068a9e97277e737421740e91f Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Fri, 5 Oct 2012 21:18:21 -0500 Subject: [PATCH 5/8] upper cased Symfony2 and also fix #symfony2 --> #symfony --- cookbook/deployment-tools.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/cookbook/deployment-tools.rst b/cookbook/deployment-tools.rst index 605c139d9b5..caeb31a9242 100644 --- a/cookbook/deployment-tools.rst +++ b/cookbook/deployment-tools.rst @@ -1,10 +1,10 @@ .. index:: single: Deployment Tools -How to deploy a symfony2 application +How to deploy a Symfony2 application ==================================== -There are several ways you can deploy a symfony2 application: +There are several ways you can deploy a Symfony2 application: * One way is moving the files manually or via ftp if you don't use versioning (e.g. git); @@ -26,7 +26,7 @@ There are several ways you can deploy a symfony2 application: * Do remember that deployment process includes all the setup and configuring, warming up caches, cleaning cache, all configuration environment required, setting of permissions, run of cron jobs, etc. All these before, during and after the deployment should be kept in - mind to properly deploy a working symfony2 application. + mind to properly deploy a working Symfony2 application. Deployment of large applications require care. The use of staging, testing, QA, continuous integration, database migrations and capability to roll back in case of failure @@ -38,7 +38,7 @@ The Tools `Capifony`_: - This tool is a deployment recipe on top of capistrano for symfony2 project + This tool is a deployment recipe on top of capistrano for Symfony2 project `Magallanes`_: @@ -63,11 +63,11 @@ Deployment services: .. tip:: - Consult your symfony community at IRC channel #symfony2 for more fresh ideas or common problems. + Consult your symfony community at IRC channel #symfony for more fresh ideas or common problems. .. _`Capifony`: https://capifony.org/ .. _`sf2debpkg`: https://github.com/liip/sf2debpkg -.. _`ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant +.. _`ant`: http://blog.sznapka.pl/deploying-Symfony2-applications-with-ant .. _`pagodabox`: https://github.com/jmather/pagoda-symfony-sonata-distribution/blob/master/Boxfile .. _`Magallanes`: https://github.com/andres-montanez/Magallanes .. _`listings`: http://knpbundles.com/search?q=deploy \ No newline at end of file From d804ecdecd69335d19c3bfab6308895f98760d4b Mon Sep 17 00:00:00 2001 From: JMather Date: Fri, 5 Oct 2012 23:35:20 -0300 Subject: [PATCH 6/8] resolved conflicts --- cookbook/deployment-tools.rst | 71 +++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 33 deletions(-) diff --git a/cookbook/deployment-tools.rst b/cookbook/deployment-tools.rst index caeb31a9242..16b2a0db71d 100644 --- a/cookbook/deployment-tools.rst +++ b/cookbook/deployment-tools.rst @@ -4,49 +4,54 @@ How to deploy a Symfony2 application ==================================== -There are several ways you can deploy a Symfony2 application: - -* One way is moving the files manually or via ftp if you don't use versioning - (e.g. git); - -* If you use versioning you could still move things manually cloning or fetching - your repository from the final server folder location. However it is advised - you make use of better tools especially in the case where you have access - capabilities such as enough permissions in a virtual private server or similar system; - -* Some projects are really large so they make use of more established tools for - deploying not only the files but really deploy a OS or package distribution - containing the sf2 project inside; - -* Another important thing to keep in mind is the handling of dependencies. - One can use composer to fetch dependencies or include them all together with the - repository. Some tools would handle this for you and even perhaps avoid fetching - dependencies when a simple copy would do; +There are several ways you can deploy a Symfony2 application. + +Let's start with a few basic examples of where developers typically begin with their +deployment strategies, and build on things from there. + +* The most basic way of deploying an application is copying the files manually via ftp + (or similar method). This is one of the worst methods because of the complete lack of + control you have over the system as the upgrade progresses. + +* When using a source code versioning tool (such as git or subversion), you can + simplify this by instead having your live installation also be a copy of your repository, + so when you're ready to upgrade it is as simple as fetching the latest updates from + your source control system. This way still causes problems when you have to incorporate + database migrations, however. It does improve upon the prior method, however, as only + the files that were changed would need to be updated, and that means your application + will be in an unstable state for far less time. + +* There are tools to help ease the pains of deployment, and their use is becoming more widespread. + Now we even have a few tools which have been specifically tailored to the requirements of + Symfony2, that take special care to ensure that everything before, during, and after a deployment + has gone correctly, and is able to halt (and roll back, if necessary) the process should an error + occur. + +Deployment of an application require care. The use of staging, testing, QA, +continuous integration, database migrations and capability to roll back in case of failure +are all strongly advised. There are simple and more complex tools and one can make +the deployment as easy (or sophisticated) as your environment requires. -* Do remember that deployment process includes all the setup and configuring, warming up caches, - cleaning cache, all configuration environment required, setting of permissions, run of - cron jobs, etc. All these before, during and after the deployment should be kept in - mind to properly deploy a working Symfony2 application. +Don't forget that deploying your application also involves updating any dependency (via +composer), migrating your database, and clearing your cache. You may even need permission +management, and the ability to add, edit, or remove cron jobs. -Deployment of large applications require care. The use of staging, testing, QA, -continuous integration, database migrations and capability to roll back in case of failure -is strongly advised. There are simple and more complex tools and one can make -the deployment as easy or sophisticated. Here we present only a few popular on the map: +Next, we will take a look at some of the more popular options. The Tools --------- `Capifony`_: - This tool is a deployment recipe on top of capistrano for Symfony2 project + This tool is a deployment recipe on top of Capistrano for Symfony2 project `Magallanes`_: - This tool is probably the one top php deployment tool capistrano-like for deploying any kind of php project + This tool is probably the one top php deployment tool Capistrano-like for deploying any kind of php project `sf2debpkg`_: - This tool helps you build a native debian package for your symfony project + This tool helps you build a native Debian package for your symfony project Bundles: @@ -54,11 +59,11 @@ Bundles: Basic scripting: - You can of course use shell, `ant`_, or other build tool to script the deploying of your project + You can of course use shell, `Ant`_, or other build tool to script the deploying of your project Deployment services: - Some services require a single file in project's git repository like `pagodabox`_ to handle all deployment + Some services require a single file in project's git repository like `PagodaBox`_ to handle all deployment .. tip:: @@ -67,7 +72,7 @@ Deployment services: .. _`Capifony`: https://capifony.org/ .. _`sf2debpkg`: https://github.com/liip/sf2debpkg -.. _`ant`: http://blog.sznapka.pl/deploying-Symfony2-applications-with-ant -.. _`pagodabox`: https://github.com/jmather/pagoda-symfony-sonata-distribution/blob/master/Boxfile +.. _`Ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant +.. _`PagodaBox`: https://github.com/jmather/pagoda-symfony-sonata-distribution/blob/master/Boxfile .. _`Magallanes`: https://github.com/andres-montanez/Magallanes .. _`listings`: http://knpbundles.com/search?q=deploy \ No newline at end of file From 9f74f2982860f6d9c8190014b6323857e8b0e765 Mon Sep 17 00:00:00 2001 From: JMather Date: Sat, 6 Oct 2012 15:49:32 -0300 Subject: [PATCH 7/8] More updates to the text -- cleaning it up a bit more. --- cookbook/deployment-tools.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/cookbook/deployment-tools.rst b/cookbook/deployment-tools.rst index 16b2a0db71d..f9c60c900cf 100644 --- a/cookbook/deployment-tools.rst +++ b/cookbook/deployment-tools.rst @@ -43,36 +43,39 @@ The Tools `Capifony`_: - This tool is a deployment recipe on top of Capistrano for Symfony2 project + This tool provides a specialized set of tools on top of Capistrano, tailored specifically to symfony and Symfony2 projects. `Magallanes`_: - This tool is probably the one top php deployment tool Capistrano-like for deploying any kind of php project + This Capistrano-like deployment tool is built in PHP, and may be easier for PHP developers to extend for their needs. `sf2debpkg`_: - This tool helps you build a native Debian package for your symfony project + This tool helps you build a native Debian package for your Symfony2 project. Bundles: - There are `listings`_ of bundles for deployment you can search and use + There are many `bundles that add deployment features`_ directly into your Symfony2 console. Basic scripting: - You can of course use shell, `Ant`_, or other build tool to script the deploying of your project + You can of course use shell, `Ant`_, or any other build tool to script the deploying of your project. -Deployment services: +Platform as a Service Providers: - Some services require a single file in project's git repository like `PagodaBox`_ to handle all deployment + PaaS is a relatively new way to deploy your application. Typically a PaaS will use a single configuration file + in your project's root directory to detrmine how to build an environment on the fly that supports your software. + One provider with confirmed Symfony2 support is `PagodaBox`_. .. tip:: - Consult your symfony community at IRC channel #symfony for more fresh ideas or common problems. + Looking for more? Talk to the community on the `Symfony IRC channel`_ #symfony (on freenode) for more information. .. _`Capifony`: https://capifony.org/ .. _`sf2debpkg`: https://github.com/liip/sf2debpkg .. _`Ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant .. _`PagodaBox`: https://github.com/jmather/pagoda-symfony-sonata-distribution/blob/master/Boxfile .. _`Magallanes`: https://github.com/andres-montanez/Magallanes -.. _`listings`: http://knpbundles.com/search?q=deploy \ No newline at end of file +.. _`bundles that add deployment features`: http://knpbundles.com/search?q=deploy +.. _`Symfony IRC channel`: http://webchat.freenode.net/?channels=symfony \ No newline at end of file From 736a00897ac1a0f95ea7168c15ad609dc1337305 Mon Sep 17 00:00:00 2001 From: JMather Date: Sun, 7 Oct 2012 23:21:39 -0300 Subject: [PATCH 8/8] Update cookbook/deployment-tools.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added suggestions by @weaverryan at https://github.com/symfony/symfony-docs/pull/1782#issuecomment-9214822 --- cookbook/deployment-tools.rst | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/cookbook/deployment-tools.rst b/cookbook/deployment-tools.rst index f9c60c900cf..f889b107473 100644 --- a/cookbook/deployment-tools.rst +++ b/cookbook/deployment-tools.rst @@ -1,8 +1,36 @@ .. index:: single: Deployment Tools +Deployment Tools +================ + +This cookbook entry will teach you the what and how of Symfony2 application deployment. + + +What is deployment? +------------------- + +Deploying software changes to your website is a critical step in the lifecycle of your application. +How you deploy the changes can affect how others perceive the stability and quality of your website. + +The typical steps taken while deploying a Symfony2 application include: + +1. Uploading your modified code to the live server +2. Updating your vendor dependencies via composer +3. Running database migrations to update any changed data structures. +4. Clearing (and perhaps more importantly, warming up) your cache + +A deployment may also include other things, such as: + +* Tagging a particular version of of your code as a release in your source control repository +* Creating a temporary staging area to build your updated setup 'offline' +* Running any tests available to ensure code and/or server stability +* Removal of any unnecessary files from `web` to keep your production environment clean +* Clearing of external cache systems (like `Memcached`_ or `Redis`_) + + How to deploy a Symfony2 application -==================================== +------------------------------------ There are several ways you can deploy a Symfony2 application. @@ -78,4 +106,6 @@ Platform as a Service Providers: .. _`PagodaBox`: https://github.com/jmather/pagoda-symfony-sonata-distribution/blob/master/Boxfile .. _`Magallanes`: https://github.com/andres-montanez/Magallanes .. _`bundles that add deployment features`: http://knpbundles.com/search?q=deploy -.. _`Symfony IRC channel`: http://webchat.freenode.net/?channels=symfony \ No newline at end of file +.. _`Symfony IRC channel`: http://webchat.freenode.net/?channels=symfony +.. _`Memcached`: http://memcached.org/ +.. _`Redis`: http://redis.io/ \ No newline at end of file