diff --git a/cookbook/deployment-tools.rst b/cookbook/deployment-tools.rst new file mode 100644 index 00000000000..f889b107473 --- /dev/null +++ b/cookbook/deployment-tools.rst @@ -0,0 +1,111 @@ +.. 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. + +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. + +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. + +Next, we will take a look at some of the more popular options. + +The Tools +--------- + +`Capifony`_: + + This tool provides a specialized set of tools on top of Capistrano, tailored specifically to symfony and Symfony2 projects. + +`Magallanes`_: + + 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 Symfony2 project. + +Bundles: + + There are many `bundles that add deployment features`_ directly into your Symfony2 console. + +Basic scripting: + + You can of course use shell, `Ant`_, or any other build tool to script the deploying of your project. + +Platform as a Service Providers: + + 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:: + + 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 +.. _`bundles that add deployment features`: http://knpbundles.com/search?q=deploy +.. _`Symfony IRC channel`: http://webchat.freenode.net/?channels=symfony +.. _`Memcached`: http://memcached.org/ +.. _`Redis`: http://redis.io/ \ No newline at end of file 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