diff --git a/components/dependency_injection/_imports-parameters-note.rst.inc b/components/dependency_injection/_imports-parameters-note.rst.inc index bcaff4c1bfc..3b479e70ba6 100644 --- a/components/dependency_injection/_imports-parameters-note.rst.inc +++ b/components/dependency_injection/_imports-parameters-note.rst.inc @@ -10,7 +10,7 @@ # app/config/config.yml imports: - - { resource: '%kernel.project_dir%/app/parameters.yml' } + - { resource: '%kernel.project_dir%/somefile.yml' } .. code-block:: xml @@ -22,11 +22,11 @@ http://symfony.com/schema/dic/services/services-1.0.xsd"> - + .. code-block:: php // app/config/config.php - $loader->import('%kernel.project_dir%/app/parameters.yml'); + $loader->import('%kernel.project_dir%/somefile.yml'); diff --git a/deployment.rst b/deployment.rst index 1ff67c815c3..dd38b4617fd 100644 --- a/deployment.rst +++ b/deployment.rst @@ -63,14 +63,13 @@ manually taking other steps (see `Common Post-Deployment Tasks`_). Using Platforms as a Service ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The specific deployment steps vary greatly from one service provider to another, -so check out the dedicated article for the service of your choose: +Using a Platform as a Service (PaaS) can be a great way to deploy your Symfony app +quickly and easily. There are many PaaS - below are a few that work well with Symfony: -.. toctree:: - :maxdepth: 1 - :glob: - - deployment/* +* `Heroku`_ +* `Platform.sh`_ +* `Azure`_ +* `fortrabbit`_ Using Build Scripts and other Tools ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -123,18 +122,16 @@ Check if your server meets the requirements by running: .. _b-configure-your-app-config-parameters-yml-file: -B) Configure your Parameters File -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +B) Configure your Environment Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Most Symfony applications define configuration parameters in a file called -``app/config/parameters.yml``. This file should *not* be deployed, because -Symfony generates it automatically using the ``app/config/parameters.yml.dist`` -file as a template (that's why ``parameters.yml.dist`` must be committed and -deployed). +Most Symfony applications read their configuration from environment variables. +While developing locally, you'll usually store these in a ``.env`` file. But on +production, instead of creating this file, you should set *real* environment variables. -If your application uses environment variables instead of these parameters, you -must define those env vars in your production server using the tools provided by -your hosting service. +How you set environment variables, depends on your setup: they can be set at the +command line, in your Nginx configuration, or via other methods provided by your +hosting service. C) Install/Update your Vendors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -237,6 +234,14 @@ kernel and return your project's root directory:: } } +Learn More +---------- + +.. toctree:: + :maxdepth: 1 + + deployment/proxies + .. _`Capifony`: https://github.com/everzet/capifony .. _`Capistrano`: http://capistranorb.com/ .. _`sf2debpkg`: https://github.com/liip/sf2debpkg @@ -249,3 +254,7 @@ kernel and return your project's root directory:: .. _`Symfony plugin`: https://github.com/capistrano/symfony/ .. _`Deployer`: http://deployer.org/ .. _`Git Tagging`: https://git-scm.com/book/en/v2/Git-Basics-Tagging +.. _`Heroku`: https://devcenter.heroku.com/articles/getting-started-with-symfony +.. _`platform.sh`: https://docs.platform.sh/frameworks/symfony.html +.. _`Azure`: https://azure.microsoft.com/en-us/develop/php/ +.. _`fortrabbit`: https://help.fortrabbit.com/install-symfony diff --git a/deployment/azure-website.rst b/deployment/azure-website.rst index b615b8c3c99..15361b9e416 100644 --- a/deployment/azure-website.rst +++ b/deployment/azure-website.rst @@ -1,459 +1,12 @@ +:orphan: + .. index:: single: Deployment; Deploying to Microsoft Azure Website Cloud -Deploying to Microsoft Azure Website Cloud -========================================== - -This step by step article describes how to deploy a small Symfony web -application to the Microsoft Azure Website cloud platform. It will explain how -to set up a new Azure website including configuring the right PHP version and -global environment variables. The document also shows how you can leverage -Git and Composer to deploy your Symfony application to the cloud. - -Setting up the Azure Website ----------------------------- - -To set up a new Microsoft Azure Website, first `sign up with Azure`_ or sign in -with your credentials. Once you're connected to your `Azure Portal`_ interface, -select the **New** panel. On this panel, use the search bar, search for -**Web App + MySQL** and choose **Web App + MySQL** by **Microsoft** and -click **Create**: - -.. image:: /_images/deployment/azure-website/step-01.png - :alt: Create a new custom Azure Website - -Step 1: Create Web Site -~~~~~~~~~~~~~~~~~~~~~~~ - -Here, you will be prompted to fill in some basic information. - -.. image:: /_images/deployment/azure-website/step-02.png - :alt: Setup the Azure Website - -For the URL, enter the URL that you would like to use for your Symfony -application, then select your **Subscription**, **Create a new Resource Group** -(which is a collection of resources that share the same lifecycle, permissions -and policies). Pick ClearDB as a **Database Provider**. Create a new **App -Service plan/Location** you will be prompted to set up your app service plan -with a name, a region and a pricing tier. Then create a new **Database**, you -will be prompted to set up your MySQL database storage with a database name and -a region. The MySQL database storage is provided by Microsoft in partnership -with ClearDB. Choose the same region you selected for App Service plan. - -Click Create to continue. - -Once you created the web site, select **All resources** in the left menu and -choose the website you just created. - -Step 2: Where Is your Source Code -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Now, select **Deployment options** under **APP DEPLOYMENT**, select **Choose -Source** and choose **Local Git repository** to configure your Azure Website -credentials. If you choose a different source like GitHub or Bitbucket you can -ignore the next step. - -.. image:: /_images/deployment/azure-website/step-03.png - :alt: Setup a local Git repository - -Once you selected **Local Git repository**, click **Setup connection** you will -be prompted to create a username and a secure password: these will become -essential identifiers to connect to the FTP server and also to push your -application code to the Git repository. - -.. image:: /_images/deployment/azure-website/step-04.png - :alt: Configure Azure Website credentials - -Congratulations! Your Azure Website is now up and running. You can check -it by browsing to the Website url you configured in the first step. You should -see the following display in your web browser: - -.. image:: /_images/deployment/azure-website/step-05.png - :alt: Azure Website is running - -The Microsoft Azure portal also provides a complete control panel for the Azure -Website. - -.. image:: /_images/deployment/azure-website/step-06.png - :alt: Azure Website Control Panel - -Your Azure Website is ready! But to run a Symfony site, you need to configure -just a few additional things. - -Configuring the Azure Website for Symfony ------------------------------------------ - -This section of the tutorial details how to configure the correct version of PHP -to run Symfony. It also shows you how to enable some mandatory PHP extensions -and how to properly configure PHP for a production environment. - -Configuring the latest PHP Runtime -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Even though Symfony only requires PHP 5.5.9 to run, it's always recommended -to use the most recent PHP version whenever possible. Earlier versions are no longer -supported by the PHP core team, but you can update it easily in Azure. - -To update your PHP version on Azure, go to the **Application settings** under -**SETTINGS** and select the version you want. - -.. image:: /_images/deployment/azure-website/step-07.png - :alt: Enabling the most recent PHP runtime from Azure Website Control Panel - -Click the **Save** button in the bottom bar to save your changes and restart -the web server. - -.. note:: - - Choosing a more recent PHP version can greatly improve runtime performance. - PHP 5.5 ships with a new built-in PHP accelerator called OPCache that - replaces APC. On an Azure Website, OPCache is already enabled and there - is no need to install and set up APC. - - The following screenshot shows the output of a :phpfunction:`phpinfo` script - run from an Azure Website to verify that PHP 7.0 is running with - OPCache enabled. - - .. image:: /_images/deployment/azure-website/step-08.png - :alt: OPCache Configuration - -Tweaking php.ini Configuration Settings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Microsoft Azure allows you to override the ``php.ini`` global configuration -settings by creating a custom ``.user.ini`` file under the project root -directory (``site/wwwroot``). - -.. code-block:: ini - - ; .user.ini - expose_php = Off - memory_limit = 256M - upload_max_filesize = 10M - -None of these settings *needs* to be overridden. The default PHP configuration -is already pretty good, so this is just an example to show how you can easily -tweak PHP internal settings by uploading your custom ``.ini`` file. - -You can either manually create this file on your Azure Website FTP server under -the ``site/wwwroot`` directory or deploy it with Git. You can get your FTP -server credentials from the Azure Website Control panel under the **Dashboard** -tab on the right sidebar. If you want to use Git, simply put your ``.user.ini`` -file at the root of your local repository and push your commits to your Azure -Website repository. - -.. note:: - - `Deploying from Git`_ is dedicated to explaining how to configure your - Azure Website Git repository and how to push the commits to be deployed. - You can also learn more about configuring PHP internal settings on the - official `PHP MSDN documentation`_ page. - -Enabling the PHP intl Extension -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**The** ``intl`` **extension is now enabled by default. The following steps are -no longer necessary.** You can check if the ``intl`` extension is enabled in the -:phpfunction:`phpinfo` page. - -However if the ``intl`` extension is not enabled you can follow these steps. - -This is the tricky part of the guide! To enable the ``intl`` extension, there is -no need to upload any DLL files as the ``php_intl.dll`` file already exists on -Azure. In fact, this file just needs to be moved into the custom website -extension directory. - -To get the ``php_intl.dll`` file under your ``site/wwwroot`` directory, simply -access the online **Kudu** tool by browsing to the following URL: - -.. code-block:: text - - https://[your-website-name].scm.azurewebsites.net - -**Kudu** is a set of tools to manage your application. It comes with a file -explorer, a command line prompt, a log stream and a configuration settings summary -page. Of course, this section can only be accessed if you're logged in to -your main Azure Website account. - -.. image:: /_images/deployment/azure-website/step-09.png - :alt: The Kudu Panel - -From the Kudu front page, click on the **Debug Console** navigation item in the -main menu and choose **CMD**. This should open the **Debug Console** page -that shows a file explorer and a console prompt below. - -In the console prompt, type the following three commands to copy the original -``php_intl.dll`` extension file into a custom website ``ext/`` directory. This -new directory must be created under the main directory ``site/wwwroot``. - -.. code-block:: terminal - - $ cd site\wwwroot - $ mkdir ext - $ copy "D:\Program Files (x86)\PHP\v5.5\ext\php_intl.dll" ext - -The whole process and output should look like this: - -.. image:: /_images/deployment/azure-website/step-10.png - :alt: Executing commands in the online Kudu Console prompt - -To complete the activation of the ``php_intl.dll`` extension, you must tell -Azure Website to load it from the newly created ``ext`` directory. This can be -done by registering a global ``PHP_EXTENSIONS`` environment variable from -the **Application settings** page of the main Azure Website control panel. - -In the **app settings** section, register the ``PHP_EXTENSIONS`` environment -variable with the value ``ext\php_intl.dll`` as shown in the screenshot below: - -.. image:: /_images/deployment/azure-website/step-11.png - :alt: Registering custom PHP extensions - -Hit "save" to confirm your changes and restart the web server. The PHP ``Intl`` -extension should now be available in your web server environment. The following -screenshot of a :phpfunction:`phpinfo` page verifies the ``intl`` extension is -properly enabled: - -.. image:: /_images/deployment/azure-website/step-12.png - :alt: Intl extension is enabled - -Great! The PHP environment setup is now complete. Next, you'll learn how -to configure the Git repository and push code to production. You'll also -learn how to install and configure the Symfony app after it's deployed. - -Deploying from Git -~~~~~~~~~~~~~~~~~~ - -First, make sure Git is correctly installed on your local machine using the -following command in your terminal: - -.. code-block:: terminal - - $ git --version - -.. note:: - - Get your Git from the `git-scm.com`_ website and follow the instructions - to install and configure it on your local machine. - -In the Azure Website Control panel, browse the **Overview** tab to get the -Git repository URL where you should push your code: - -.. image:: /_images/deployment/azure-website/step-13.png - :alt: Git deployment panel - -Now, you'll want to connect your local Symfony application with this remote -Git repository on Azure Website. If your Symfony application is not yet stored -with Git, you must first create a Git repository in your Symfony application -directory with the ``git init`` command and commit to it with the ``git commit`` -command. - -Also, make sure your Symfony repository has a ``.gitignore`` file at its root -directory with at least the following contents: - -.. code-block:: text - - /var/bootstrap.php.cache - /var/cache/* - /app/config/parameters.yml - /var/log/* - !var/cache/.gitkeep - !var/log/.gitkeep - /var/SymfonyRequirements.php - /build/ - /vendor/ - /bin/ - /composer.phar - /public/index.php - /public/bundles/ - /public/config.php - -The ``.gitignore`` file asks Git not to track any of the files and directories -that match these patterns. This means these files won't be deployed to the Azure -Website. - -Now, from the command line on your local machine, type the following at the -root of your Symfony project: - -.. code-block:: terminal - - $ git remote add azure https://@.scm.azurewebsites.net:443/.git - $ git push azure master - -Don't forget to replace the values enclosed by ``<`` and ``>`` with your custom -settings displayed in the **Deployment** tab of your Azure Website panel. The -``git remote`` command connects the Azure Website remote Git repository and -assigns an alias to it with the name ``azure``. The second ``git push`` command -pushes all your commits to the remote ``master`` branch of your remote ``azure`` -Git repository. - -The deployment with Git should produce an output similar to the screenshot -below: - -.. image:: /_images/deployment/azure-website/step-14.png - :alt: Deploying files to the Git Azure Website repository - -The code of the Symfony application has now been deployed to the Azure Website -which you can browse from the file explorer of the Kudu application. You should -see the ``config/``, ``src/`` and ``public/`` directories under your ``site/wwwroot`` -directory on the Azure Website filesystem. - -Configure the Symfony Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -PHP has been configured and your code has been pushed with Git. The last -step is to configure the application and install the third party dependencies -it requires that aren't tracked by Git. Switch back to the online **Console** -of the Kudu application and execute the following commands in it: - -.. code-block:: terminal - - $ cd site\wwwroot - $ curl -sS https://getcomposer.org/installer | php - $ php composer.phar install - -The ``curl`` command retrieves and downloads the Composer command line tool and -installs it at the root of the ``site/wwwroot`` directory. Then, running -the Composer ``install`` command downloads and installs all necessary third-party -libraries. - -This may take a while depending on the number of third-party dependencies -you've configured in your ``composer.json`` file. - - -At the end of the ``composer install`` command, you will be prompted to fill in -the values of some Symfony settings like database credentials, locale, mailer -credentials, CSRF token protection, etc. These parameters come from the -``app/config/parameters.yml.dist`` file. - -.. image:: /_images/deployment/azure-website/step-15.png - :alt: Configuring Symfony global parameters - -The most important thing in this article is to correctly set up your database -settings. You can get your MySQL database settings in the **Application -settings** page. Simply click on the **Show connection string values** link to -make them appear. - -.. image:: /_images/deployment/azure-website/step-16.png - :alt: MySQL database settings - -The displayed MySQL database settings should be something similar to the code -below. Of course, each value depends on what you've already configured. - -.. code-block:: text - - Database=mysymfonyMySQL;Data Source=eu-cdbr-azure-north-c.cloudapp.net;User Id=bff2481a5b6074;Password=bdf50b42 - -Switch back to the console and answer the prompted questions and provide the -following answers. Don't forget to adapt the values below with your real values -from the MySQL connection string. - -.. code-block:: text - - database_driver: pdo_mysql - database_host: u-cdbr-azure-north-c.cloudapp.net - database_port: null - database_name: mysymfonyMySQL - database_user: bff2481a5b6074 - database_password: bdf50b42 - // ... - -Don't forget to answer all the questions. It's important to set a unique random -string for the ``secret`` variable. For the mailer configuration, Azure Website -doesn't provide a built-in mailer service. You should consider configuring -the host-name and credentials of some other third-party mailing service if -your application needs to send emails. - -Your Symfony application is now configured and should be almost operational. The -final step is to build the database schema. This can easily be done with the -command line interface if you're using Doctrine. In the online **Console** tool -of the Kudu application, run the following command to mount the tables into your -MySQL database. - -.. code-block:: terminal - - $ php bin/console doctrine:schema:update --force - -This command builds the tables and indexes for your MySQL database. If your -Symfony application is more complex than a basic Symfony Standard Edition, you -may have additional commands to execute for setup (see :doc:`/deployment`). - -Make sure that your application is running by browsing the ``index.php`` front -controller with your web browser and the following URL: - -.. code-block:: terminal - - http://.azurewebsites.net/public/index.php - -If Symfony is correctly installed, you should see the front page of your Symfony -application showing. - -Configure the Web Server -~~~~~~~~~~~~~~~~~~~~~~~~ - -At this point, the Symfony application has been deployed and works perfectly on -the Azure Website. However, the ``web`` folder is still part of the URL, which -you definitely don't want. But don't worry! You can easily configure the web -server to point to the ``web`` folder and remove the ``web`` in the URL (and -guarantee that nobody can access files outside of the ``web`` directory.) - -To do this, create and deploy (see previous section about Git) the following -``web.config`` file. This file must be located at the root of your project -next to the ``composer.json`` file. This file is the Microsoft IIS Server -equivalent to the well-known ``.htaccess`` file from Apache. For a Symfony -application, configure it with the following content: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -As you can see, the latest rule ``RewriteRequestsToPublic`` is responsible for -rewriting any URLs to the ``public/index.php`` front controller which allows you to -skip the ``public/`` folder in the URL. The first rule called ``BlockAccessToPublic`` -matches all URL patterns that contain the ``public/`` folder and serves a -``403 Forbidden`` HTTP response instead. This example is based on Benjamin -Eberlei's sample you can find on GitHub in the `SymfonyAzureEdition`_ bundle. - -Deploy this file under the ``site/wwwroot`` directory of the Azure Website and -browse to your application without the ``public/index.php`` segment in the URL. - -Conclusion ----------- +Deploying to Microsoft Azure +============================ -Nice work! You've now deployed your Symfony application to the Microsoft -Azure Website Cloud platform. You also saw that Symfony can be easily configured -and executed on a Microsoft IIS web server. The process is simple and easy -to implement. And as a bonus, Microsoft is continuing to reduce the number -of steps needed so that deployment becomes even easier. +If you want information about deploying to Azure, see their official documentation: +`Create your PHP web application on Azure`_ -.. _`sign up with Azure`: https://azure.microsoft.com/free/ -.. _`Azure Portal`: https://portal.azure.com -.. _`PHP MSDN documentation`: http://blogs.msdn.com/b/silverlining/archive/2012/07/10/configuring-php-in-windows-azure-websites-with-user-ini-files.aspx -.. _`git-scm.com`: http://git-scm.com/download -.. _`SymfonyAzureEdition`: https://github.com/beberlei/symfony-azure-edition/ +.. _`Create your PHP web application on Azure`: https://azure.microsoft.com/en-us/develop/php/ diff --git a/deployment/fortrabbit.rst b/deployment/fortrabbit.rst index 8e2028ee821..f13bf4f0ad4 100644 --- a/deployment/fortrabbit.rst +++ b/deployment/fortrabbit.rst @@ -1,285 +1,12 @@ +:orphan: + .. index:: single: Deployment; Deploying to fortrabbit.com Deploying to fortrabbit ======================= -This step-by-step article describes how to deploy a Symfony web application to -`fortrabbit`_. You can read more about using Symfony with fortrabbit on the -official fortrabbit `Symfony install guide`_. - -Setting up fortrabbit ---------------------- - -Before getting started, you should have done a few things on the fortrabbit side: - -* `Sign up`_; -* Add an SSH key to your Account (to deploy via Git); -* Create an App. - -Preparing your Application --------------------------- - -You don't need to change any code to deploy a Symfony application to fortrabbit. -But it requires some minor tweaks to its configuration. - -Configure Logging -~~~~~~~~~~~~~~~~~ - -Per default Symfony logs to a file. Modify the ``app/config/config_prod.yml`` file -to redirect it to :phpfunction:`error_log`: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config_prod.yml - monolog: - # ... - handlers: - nested: - type: error_log - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - // app/config/config_prod.php - $container->loadFromExtension('monolog', array( - // ... - 'handlers' => array( - 'nested' => array( - 'type' => 'error_log', - ), - ), - )); - -Configuring Database Access & Session Handler -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can use the fortrabbit App Secrets to attain your database credentials. -Create the file ``app/config/config_prod_secrets.php`` with the following -contents:: - - // get the path to the secrects.json file - $secrets = getenv("APP_SECRETS") - if (!$secrets) { - return; - } - - // read the file and decode json to an array - $secrets = json_decode(file_get_contents($secrets), true); - - // set database parameters to the container - if (isset($secrets['MYSQL'])) { - $container->setParameter('database_driver', 'pdo_mysql'); - $container->setParameter('database_host', $secrets['MYSQL']['HOST']); - $container->setParameter('database_name', $secrets['MYSQL']['DATABASE']); - $container->setParameter('database_user', $secrets['MYSQL']['USER']); - $container->setParameter('database_password', $secrets['MYSQL']['PASSWORD']); - } - - // check if the Memcache component is present - if (isset($secrets['MEMCACHE'])) { - $memcache = $secrets['MEMCACHE']; - $handlers = array(); - - foreach (range(1, $memcache['COUNT']) as $num) { - $handlers[] = $memcache['HOST'.$num].':'.$memcache['PORT'.$num]; - } - - // apply ini settings - ini_set('session.save_handler', 'memcached'); - ini_set('session.save_path', implode(',', $handlers)); - - if ("2" === $memcache['COUNT']) { - ini_set('memcached.sess_number_of_replicas', 1); - ini_set('memcached.sess_consistent_hash', 1); - ini_set('memcached.sess_binary', 1); - } - } - -Make sure this file is imported into the main config file: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config_prod.yml - imports: - - { resource: config.yml } - - { resource: config_prod_secrets.php } - - # .. - framework: - session: - # set handler_id to null to use default session handler from php.ini (memcached) - handler_id: ~ - # .. - - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php - - // app/config/config_prod.php - $loader->import('config.php'); - $loader->import('config_prod_secrets.php'); - - $container->loadFromExtension('framework', array( - 'session' => array( - 'handler_id' => null, - ), - )); - - // ... - -Configuring the Environment in the Dashboard --------------------------------------------- - -PHP Settings -~~~~~~~~~~~~ - -The PHP version and enabled extensions are configurable under the PHP settings -of your App within the fortrabbit Dashboard. - -Environment Variables -~~~~~~~~~~~~~~~~~~~~~ - -Set the ``SYMFONY_ENV`` environment variable to ``prod`` to make sure the right -config files get loaded. ENV vars are configuable in fortrabbit Dashboard as well. - -Document Root -~~~~~~~~~~~~~ - -The document root is configurable for every custom domain you setup for your App. -The default is ``/htdocs``, but for Symfony you probably want to change it to -``/htdocs/web``. You also do so in the fortrabbit Dashboard under ``Domain`` settings. - -Deploying to fortrabbit ------------------------ - -It is assumed that your codebase is under version-control with Git and dependencies -are managed with Composer (locally). - -Every time you push to fortrabbit composer install runs before your code gets -deployed. To finetune the deployment behavior put a `fortrabbit.yml`_. deployment -file (optional) in the project root. - -Add fortrabbit as a (additional) Git remote and add your configuration changes: - -.. code-block:: terminal - - $ git remote add fortrabbit git@deploy.eu2.frbit.com:.git - $ git add composer.json composer.lock - $ git add app/config/config_prod_secrets.php - -Commit and push - -.. code-block:: terminal - - $ git commit -m 'fortrabbit config' - $ git push fortrabbit master -u - -.. note:: - - Replace ```` with the name of your fortrabbit App. - -.. code-block:: terminal - - Commit received, starting build of branch master - - ––––––––––––––––––––––– ∙ƒ ––––––––––––––––––––––– - - B U I L D - - Checksum: - def1bb29911a62de26b1ddac6ef97fc76a5c647b - - Deployment file: - fortrabbit.yml - - Pre-script: - not found - 0ms - - Composer: - - - - - Loading composer repositories with package information - Installing dependencies (including require-dev) from lock file - Nothing to install or update - Generating autoload files - - - - - - 172ms - - Post-script: - not found - 0ms - - R E L E A S E - - Packaging: - 930ms - - Revision: - 1455788127289043421.def1bb29911a62de26b1ddac6ef97fc76a5c647b - - Size: - 9.7MB - - Uploading: - 500ms - - Build & release done in 1625ms, now queued for final distribution. - - -.. note:: - - The first ``git push`` takes much longer as all composer dependencies get - downloaded. All subsequent deploys are done within seconds. - -That's it! Your application is being deployed on fortrabbit. More information -about `database migrations and tunneling`_ can be found in the fortrabbit -documentation. +For details on deploying to fortrabbit, see their official documentation: +`Install Symfony`_ -.. _`fortrabbit`: https://www.fortrabbit.com -.. _`Symfony install guide`: https://help.fortrabbit.com/install-symfony -.. _`fortrabbit.yml`: https://help.fortrabbit.com/deployment-file-v2 -.. _`database migrations and tunneling`: https://help.fortrabbit.com/install-symfony-2#toc-migrate-amp-other-database-commands -.. _`Sign up`: https://dashboard.fortrabbit.com +.. _`Install Symfony`: https://help.fortrabbit.com/install-symfony-3-uni diff --git a/deployment/heroku.rst b/deployment/heroku.rst index d34024af5f3..a7527805bd2 100644 --- a/deployment/heroku.rst +++ b/deployment/heroku.rst @@ -1,331 +1,12 @@ +:orphan: + .. index:: single: Deployment; Deploying to Heroku Cloud -Deploying to Heroku Cloud -========================= - -This step by step article describes how to deploy a Symfony web application to -the Heroku cloud platform. Its contents are based on `the original article`_ -published by Heroku. - -Setting up ----------- - -To set up a new Heroku website, first `sign up with Heroku`_ or sign in -with your credentials. Then download and install the `Heroku Toolbelt`_ 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 Symfony application to Heroku doesn't require any change in its -code, but it requires some minor tweaks to its configuration. - -By default, the Symfony app will log into your application's ``var/log/`` -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, -Symfony 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 - - # app/config/config_prod.yml - monolog: - # ... - handlers: - # ... - nested: - # ... - 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:: terminal - - $ 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 ------------------------------------- - -Before your first deploy, you need to do just three more things, which are explained -below: - -#. :ref:`Create a Procfile ` - -#. :ref:`Set the Environment to prod ` - -#. :ref:`Push your Code to Heroku ` - -.. _heroku-procfile: -.. _creating-a-procfile: - -1) Create a Procfile -~~~~~~~~~~~~~~~~~~~~ - -By default, Heroku will launch an Apache web server together with PHP to serve -applications. However, a special circumstance apply to Symfony applications: -the document root is in the ``public/`` directory and not in the root directory -of the application. - -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: vendor/bin/heroku-php-apache2 public/ - -.. note:: - - If you prefer to use Nginx, which is also available on Heroku, you can create - a configuration file for it and point to it from your Procfile as described - in the `Heroku documentation`_: - - .. code-block:: text - - web: vendor/bin/heroku-php-nginx -C nginx_app.conf public/ - -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:: terminal - - $ echo "web: vendor/bin/heroku-php-apache2 public/" > Procfile - $ git add . - $ git commit -m "Procfile for Apache and PHP" - [master 35075db] Procfile for Apache and PHP - 1 file changed, 1 insertion(+) - -.. _heroku-setting-env-to-prod: -.. _setting-the-prod-environment: - -2) Set the Environment to prod -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -During a deployment, Heroku runs ``composer install --no-dev`` to install all the -dependencies your application requires. However, typical `post-install-commands`_ -in ``composer.json``, e.g. to install assets or clear (or pre-warm) caches, run -using Symfony's ``dev`` environment by default. - -This is clearly not what you want - the app runs in "production" (even if you -use it just for an experiment, or as a staging environment), and so any build -steps should use the same ``prod`` environment as well. - -Thankfully, the solution to this problem is very simple: Symfony will pick up an -environment variable named ``SYMFONY_ENV`` and use that environment if nothing -else is explicitly set. As Heroku exposes all `config vars`_ as environment -variables, you can issue a single command to prepare your app for a deployment: - -.. code-block:: terminal - - $ heroku config:set SYMFONY_ENV=prod - -.. caution:: - - Be aware that dependencies from ``composer.json`` listed in the ``require-dev`` - section are never installed during a deploy on Heroku. This may cause problems - if your Symfony environment relies on such packages. The solution is to move these - packages from ``require-dev`` to the ``require`` section. - -.. _heroku-push-code: -.. _pushing-to-heroku: - -3) Push your Code 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:: text - - 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:: terminal - - $ 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 public/bundles/framework - Installing assets for Acme\DemoBundle into public/bundles/acmedemo - Installing assets for Sensio\Bundle\DistributionBundle into public/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:: terminal - - $ heroku open - Opening mighty-hamlet-1981... done - -You should be seeing your Symfony application in your browser. - -.. caution:: - - If you take your first steps on Heroku using a fresh installation of - the Symfony Standard Edition, you may run into a 404 page not found error. - This is because the route for ``/`` is defined by the AcmeDemoBundle, but the - AcmeDemoBundle is only loaded in the dev environment (check out your - ``AppKernel`` class). Try opening ``/app/example`` from the AppBundle. - -Custom Compile Steps -~~~~~~~~~~~~~~~~~~~~ - -If you wish to execute additional custom commands during a build, you can leverage -Heroku's `custom compile steps`_. Imagine you want to remove the ``dev`` front controller -from your production environment on Heroku in order to avoid a potential vulnerability. -Adding a command to remove ``public/index.php`` to Composer's `post-install-commands`_ would -work, but it also removes the controller in your local development environment on each -``composer install`` or ``composer update`` respectively. Instead, you can add a -`custom Composer command`_ named ``compile`` (this key name is a Heroku convention) to the -``scripts`` section of your ``composer.json``. The listed commands hook into Heroku's deploy -process: - -.. code-block:: json - - { - "scripts": { - "compile": [ - "rm public/index.php" - ] - } - } - -This is also very useful to build assets on the production system, e.g. with Assetic: - -.. code-block:: json - - { - "scripts": { - "compile": [ - "bin/console assetic:dump" - ] - } - } - -.. sidebar:: Node.js Dependencies - - Building assets may depend on node packages, e.g. ``uglifyjs`` or ``uglifycss`` - for asset minification. Installing node packages during the deploy requires a node - installation. But currently, Heroku compiles your app using the PHP buildpack, which - is auto-detected by the presence of a ``composer.json`` file, and does not include a - node installation. Because the Node.js buildpack has a higher precedence than the PHP - buildpack (see `Heroku buildpacks`_), adding a ``package.json`` listing your node - dependencies makes Heroku opt for the Node.js buildpack instead: - - .. code-block:: json - - { - "name": "myApp", - "engines": { - "node": "0.12.x" - }, - "dependencies": { - "uglifycss": "*", - "uglify-js": "*" - } - } - - With the next deploy, Heroku compiles your app using the Node.js buildpack and - your npm packages become installed. On the other hand, your ``composer.json`` is - now ignored. To compile your app with both buildpacks, Node.js *and* PHP, you need - to use both buildpacks. To override buildpack auto-detection, you - need to explicitly set the buildpack: - - .. code-block:: terminal - - $ heroku buildpacks:set heroku/nodejs - Buildpack set. Next release on your-application will use heroku/nodejs. - Run git push heroku master to create a new release using this buildpack. - $ heroku buildpacks:set heroku/php --index 2 - Buildpack set. Next release on your-application will use: - 1. heroku/nodejs - 2. heroku/php - Run git push heroku master to create a new release using these buildpacks. +Deploying to Heroku +=================== - With the next deploy, you can benefit from both buildpacks. This setup also enables - your Heroku environment to make use of node based automatic build tools like - `Grunt`_ or `gulp`_. +To deploy to Heroku, see their official documentation: +`Getting Started with Symfony on Heroku`_. -.. _`the original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2 -.. _`sign up with Heroku`: https://signup.heroku.com/signup/dc -.. _`Heroku Toolbelt`: https://devcenter.heroku.com/articles/getting-started-with-php#set-up -.. _`getting Started with PHP on Heroku`: 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 -.. _`post-install-commands`: https://getcomposer.org/doc/articles/scripts.md -.. _`config vars`: https://devcenter.heroku.com/articles/config-vars -.. _`custom compile steps`: https://devcenter.heroku.com/articles/php-support#custom-compile-step -.. _`custom Composer command`: https://getcomposer.org/doc/articles/scripts.md#writing-custom-commands -.. _`Heroku buildpacks`: https://devcenter.heroku.com/articles/buildpacks -.. _`Grunt`: http://gruntjs.com -.. _`gulp`: http://gulpjs.com -.. _`Heroku documentation`: https://devcenter.heroku.com/articles/custom-php-settings#nginx +.. _`Getting Started with Symfony on Heroku`: https://devcenter.heroku.com/articles/getting-started-with-symfony diff --git a/deployment/platformsh.rst b/deployment/platformsh.rst index 6d9d622a714..c124da18674 100644 --- a/deployment/platformsh.rst +++ b/deployment/platformsh.rst @@ -1,196 +1,12 @@ +:orphan: + .. index:: single: Deployment; Deploying to Platform.sh Deploying to Platform.sh ======================== -This step-by-step article describes how to deploy a Symfony web application to -`Platform.sh`_. You can read more about using Symfony with Platform.sh on the -official `Platform.sh documentation`_. - -Deploy an Existing Site ------------------------ - -In this guide, it is assumed your codebase is already versioned with Git. - -Get a Project on Platform.sh -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You need to `subscribe to a Platform.sh plan`_ and go through the checkout process. -Once your project is ready, give it a name and choose: **Import an existing site**. - -Prepare Your Application -~~~~~~~~~~~~~~~~~~~~~~~~ - -To deploy your Symfony application on Platform.sh, you simply need to add a -``.platform.app.yaml`` at the root of your Git repository which will tell -Platform.sh how to deploy your application (read more about -`Platform.sh configuration files`_). - -.. code-block:: yaml - - # .platform.app.yaml - - # This file describes an application. You can have multiple applications - # in the same project. - - # The name of this app. Must be unique within a project. - name: myphpproject - - # The type of the application to build. - type: php:5.6 - build: - flavor: composer - - # The relationships of the application with services or other applications. - # The left-hand side is the name of the relationship as it will be exposed - # to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand - # side is in the form `:`. - relationships: - database: 'mysql:mysql' - - # The configuration of app when it is exposed to the web. - web: - # The public directory of the app, relative to its root. - document_root: '/web' - # The front-controller script to send non-static requests to. - passthru: '/index.php' - - # The size of the persistent disk of the application (in MB). - disk: 2048 - - # The mounts that will be performed when the package is deployed. - mounts: - '/var/cache': 'shared:files/cache' - '/var/log': 'shared:files/log' - '/var/sessions': 'shared:files/sessions' - - # The hooks that will be performed when the package is deployed. - hooks: - build: | - rm public/index.php - bin/console --env=prod assetic:dump --no-debug - deploy: | - bin/console --env=prod cache:clear - -For best practices, you should also add a ``.platform`` folder at the root of -your Git repository which contains the following files: - -.. code-block:: yaml - - # .platform/routes.yaml - "http://{default}/": - type: upstream - # the first part should be your project name - upstream: 'myphpproject:php' - -.. code-block:: yaml - - # .platform/services.yaml - mysql: - type: mysql - disk: 2048 - -An example of these configurations can be found on `GitHub`_. The list of -`available services`_ can be found on the Platform.sh documentation. - -Configure Database Access -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Platform.sh overrides your database specific configuration via importing the -following file (it's your role to add this file to your code base):: - - // app/config/parameters_platform.php - setParameter('database_driver', 'pdo_' . $endpoint['scheme']); - $container->setParameter('database_host', $endpoint['host']); - $container->setParameter('database_port', $endpoint['port']); - $container->setParameter('database_name', $endpoint['path']); - $container->setParameter('database_user', $endpoint['username']); - $container->setParameter('database_password', $endpoint['password']); - $container->setParameter('database_path', ''); - } - - # Store session into /tmp. - ini_set('session.save_path', '/tmp/sessions'); - -Make sure this file is listed in your *imports* (after the default ``parameters.yml`` -file): - -.. code-block:: yaml - - # app/config/config.yml - imports: - - { resource: parameters.yml } - - { resource: parameters_platform.php } - -Deploy your Application -~~~~~~~~~~~~~~~~~~~~~~~ - -Now you need to add a remote to Platform.sh in your Git repository (copy the -command that you see on the Platform.sh web UI): - -.. code-block:: terminal - - $ git remote add platform [PROJECT-ID]@git.[CLUSTER].platform.sh:[PROJECT-ID].git - -``PROJECT-ID`` - Unique identifier of your project. Something like ``kjh43kbobssae`` -``CLUSTER`` - Server location where your project is deployed. It can be ``eu`` or ``us`` - -Commit the Platform.sh specific files created in the previous section: - -.. code-block:: terminal - - $ git add .platform.app.yaml .platform/* - $ git add app/config/config.yml app/config/parameters_platform.php - $ git commit -m "Adding Platform.sh configuration files." - -Push your code base to the newly added remote: - -.. code-block:: terminal - - $ git push platform master - -That's it! Your application is being deployed on Platform.sh and you'll soon be -able to access it in your browser. - -Every code change that you do from now on will be pushed to Git in order to -redeploy your environment on Platform.sh. - -More information about `migrating your database and files`_ can be found -on the Platform.sh documentation. - -Deploy a new Site ------------------ - -You can start a new `Platform.sh project`_. Choose the development plan and go -through the checkout process. - -Once your project is ready, give it a name and choose: **Create a new site**. -Choose the *Symfony* stack and a starting point such as *Standard*. - -That's it! Your Symfony application will be bootstrapped and deployed. You'll -soon be able to see it in your browser. +To deploy to Platform.sh, see their official documentation: +`Symfony Platform.sh Documentation`_. -.. _`Platform.sh`: https://platform.sh -.. _`Platform.sh documentation`: https://docs.platform.sh/frameworks/symfony.html -.. _`Platform.sh project`: https://accounts.platform.sh/platform/buy-now -.. _`subscribe to a Platform.sh plan`: https://accounts.platform.sh/platform/buy-now -.. _`Platform.sh configuration files`: https://docs.platform.sh/configuration/services.html -.. _`GitHub`: https://github.com/platformsh/platformsh-examples -.. _`available services`: https://docs.platform.sh/reference/configuration-files/#configure-services -.. _`migrating your database and files`: https://docs.platform.sh/tutorials/migrating.html +.. _`Symfony Platform.sh Documentation`: https://docs.platform.sh/frameworks/symfony.html