Added case study to work on existing website on a Vagrant VM.

developer/case-studies/download-to-vagrant.rst

@@ -0,0 +1,124 @@
+.. _download_to_vagrant:
+
+======================================================
+Download a website on my computer to work with Vagrant
+======================================================
+
+On the production server:
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Generate a database dump on your production server.
+
+.. code-block:: bash
+
+    mysqldump -uMYUSER -pMYPASSWORD MYDATABASE > database-YYYY-mm-dd.sql
+
+Then download it on your computer. You can also use *phpmyadmin* web tool to export
+your database tables. Make sure to disable *foreign key verification* and add the
+*DROP IF EXISTS* directive on *phpmyadmin* export form.
+
+On your computer:
+^^^^^^^^^^^^^^^^^
+
+1. Clone Roadiz on your favorite folder, choose well between master or develop branch
+if you want the stable version or the latest features.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites;
+    # Here I choose the develop branch, because I’m warrior
+    git clone -b develop https://github.com/roadiz/roadiz.git mysuperwebsite;
+
+
+2. Clone your website theme in Roadiz ``themes/`` folder, choose well your branch too. If you already
+have a *develop* branch, clone with ``-b develop`` option.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite/themes;
+    # My theme already has a develop branch so…
+    git clone -b develop git@github.com:johndoe/SuperTheme.git SuperTheme;
+
+3. Init *git-flow* on the theme. You should always work on *develop*. *Master* branch is only for releases.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite/themes/SuperTheme;
+    git flow init;
+    # Git flow should checkout on develop branch for you
+
+4. Install Roadiz’ *composer* dependencies (after cloning the theme to be sure that all *composer* dependencies are loaded)
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite;
+    composer install --no-dev;
+
+5. Launch your Vagrant environment. Do not to automatically provision your VM if you want to choose what tool to install.
+
+.. code-block:: bash
+
+    vagrant up --no-provision;
+    # ... lots of lines, bla bla bla
+
+Choose tools to install on your VM, ``roadiz`` provisioner is mandatory… obviously, ``devtools`` provisioner will
+install *Composer*, *Node.js*, *Grunt* and *Bower* commands. If you have lots of website on your computer, it’s better to
+install these tools directly on your host machine, they will be more effective than on the VM. And you will be able to
+take advantage of *Composer* and *NPM* cache between your dev websites.
+
+.. code-block:: bash
+
+    # Everything
+    vagrant provision --provision-with roadiz,phpmyadmin,mailcatcher,solr,devtools
+    # OR on a dev computer
+    vagrant provision --provision-with roadiz,phpmyadmin,mailcatcher,solr
+
+
+6. Import your database dump. First, you’ll need to copy it into your Roadiz website to make it
+available within your Vagrant VM. Then import it in your VM using the ``mysql`` tool.
+
+.. code-block:: bash
+
+    mv ~/Downloads/database-YYYY-mm-dd.sql ~/Documents/Websites/mysuperwebsite/database-YYYY-mm-dd.sql;
+    cd ~/Documents/Websites/mysuperwebsite;
+    # Enter your VM
+    vagrant ssh;
+    # Your website is located in /var/www folder
+    cd /var/www;
+    mysql -uroadiz -proadiz roadiz < database-YYYY-mm-dd.sql;
+    # Exit your VM
+    exit;
+
+7. Update your conf/config.yml file to fill in your mysql credentials.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite;
+    # composer should have create a starter config file for you
+    subl conf/config.yml; # If you work SublimeText
+
+8. Use the ``bin/roadiz generate:nsentities`` to regenerate *Doctrine* entities existing in database but not as files.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite;
+    vagrant ssh;
+    cd /var/www;
+    bin/roadiz generate:nsentities;
+    # You may have to check database schema if your production website is not up to
+    # date with latest Roadiz
+    bin/roadiz orm:schema-tool:update --dump-sql --force;
+
+9. Download your production documents to your dev VM. You don’t have to do this within your VM.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite/files;
+    rsync -avcz -e "ssh -p 22" myuser@superwebsite.com:~/path/to/roadiz/files/ ./
+    # do not forget ending slashes in both paths.
+
+10. If you are using a Vagrant VM you have to add your IP address to the ``dev.php`` file
+to authorize your host computer to use the development environment.
+
+11. Connect to ``http://localhost:8080/dev.php`` to begin. Every outgoing emails should be catched
+by *Mailcatcher*. You can see them at address ``http://localhost:1080``.

developer/case-studies/index.rst

@@ -0,0 +1,11 @@
+
+============
+Case studies
+============
+
+Some step-to-step guides to work with Roadiz.
+
+.. toctree::
+   :maxdepth: 1
+
+   download-to-vagrant.rst

developer/first-steps/installation.rst

@@ -4,8 +4,8 @@
 Installation
 ============
 
-Download sources
-----------------
+Get Roadiz sources
+------------------
 
 Roadiz can be downloaded in two different ways:
 
@@ -21,17 +21,20 @@ An example virtual host is provided in source-code for each server:
 * ``samples/apache.conf``
 * ``samples/nginx.conf``
 
-You just have to customize your root path and server name. *Nginx* has built-in support for *php-fpm* whereas *Apache* must be configured with *fastcgi* to do the same.
+You just have to customize your root path and server name. *Nginx* has built-in support
+for *php-fpm* whereas *Apache* must be configured with *fastcgi* to do the same.
 
 These example files will provide basic security configuration for private access folders:
-such as ``conf`` or ``files/fonts`` folders. They will also configure your server to redirect all non static requests
-to Roadiz *front-controller*.
+such as ``conf`` or ``files/fonts`` folders. They will also configure your server
+to redirect all non static requests to Roadiz *front-controller*.
 
 .. note::
-    **For shared hosting plan owners**, if you can’t modify your virtual host definition, don’t panic, Roadiz has a built-in CLI command to generate ``.htaccess`` files for you.
+    **For shared hosting plan owners**, if you can’t modify your virtual host definition,
+    don’t panic, Roadiz has a built-in CLI command to generate ``.htaccess`` files for you.
     Just execute ``bin/roadiz generate:htaccess`` after cloning Roadiz sources and running Composer.
-    In the other hand, if you are using *Apache* and have access to your virtual host, we strongly recommend you to use our sample configuration and disable ``.htaccess`` files: performances are at their best
-    without them.
+    In the other hand, if you are using *Apache* and have access to your virtual host,
+    we strongly recommend you to use our sample configuration and disable ``.htaccess`` files:
+    performances are at their best without them.
 
 When your HTTP server is ready to go, download *Roadiz* latest version using Git:
 
@@ -40,7 +43,9 @@ When your HTTP server is ready to go, download *Roadiz* latest version using Git
     cd your/webroot/folder;
     git clone git@github.com:roadiz/roadiz.git ./;
 
-Use `Composer <https://getcomposer.org/doc/00-intro.md#globally>`_ to download Roadiz dependencies and to build PHP class autolader. We even set up some post-scripts which will copy a new ``config.yml``, ``dev.php`` and ``install.php`` files for you.
+Use `Composer <https://getcomposer.org/doc/00-intro.md#globally>`_ to download Roadiz dependencies
+and to build PHP class autolader. We even set up some post-scripts which will copy
+a new ``config.yml``, ``dev.php`` and ``install.php`` files for you.
 
 .. code-block:: bash
     # Install Roadiz dependencies, prepare a fresh config file and your

developer/first-steps/moving.rst

@@ -8,38 +8,41 @@ Before moving your website, make sure you have backed up your data:
 * Dump your database, using ``mysqldump`` or ``pg_dump`` tools.
 * Archive your ``files/`` folder, it contains all your documents and font files.
 
-Moving to a SSH+Git hosting plan
---------------------------------
+Moving to a SSH+Git hosting plan or an other development machine
+----------------------------------------------------------------
 
-From this point you can install your new webserver, as described in :ref:`Install section <getting-started>`.
+From this point you can install your new webserver, as described in :ref:`Install section <installation>`.
+Pay attention that if your theme needs some additionnal *composer* dependencies you should
+*clone/copy* it into your *themes/* folder **before** running ``composer install --no-dev``. That way
+*composer* will download theme libraries at the same time as Roadiz’ ones (:ref:`See how to use Composer in your themes <theme_composer>`).
 
 Then import your dump and files into your new server.
 
 Once you’ve imported your database, you must edit manually your `conf/config.yml`,
 you can reuse the former server’s one and adapt its database credentials.
 
 .. warning::
-    **Do not perform any schema update if no *gen-src\\GeneratedNodeSources* classes is available**,
+    **Do not perform any schema update if no gen-src\\GeneratedNodeSources classes is available**,
     it will erase your NodesSources data as their entities files haven’t been generated yet.
 
-When you have edited your ``conf/config.yml`` file, regenerate your entities source files
+When you have edited your ``conf/config.yml`` file, regenerate your *Doctrine* entities class files:
 
 .. code-block:: bash
 
     bin/roadiz generate:nsentities;
 
-Now you can perform a schema update without losing your nodes data
+Now you can perform a schema update without losing your nodes data:
 
 .. code-block:: bash
 
     bin/roadiz orm:schema-tool:update --dump-sql;
     bin/roadiz orm:schema-tool:update --force;
-
     bin/roadiz cache:clear --env=prod
 
 .. note::
     If you are using an OPcode cache like XCache or APC, you’ll need to purge cache manually
-    because it can't be done from a CLI interface as they are shared cache engines.
+    because it can't be done from a CLI interface as they are shared cache engines. The most
+    effective way is to restart your *PHP-FPM* service or *Apache* if your are using *mod_php*.
 
 Synchronize documents and fonts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -53,6 +56,14 @@ as it will upload only newer files and it is much faster.
     # Do not forget ending slash after each path!
     rsync -avcz -e "ssh -p 22" /path/to/roadiz/files/ user@my-prod-server.com:/path/to/roadiz/files/
 
+It works in the other way too. If you want to work on your local copy with up to date files and
+fonts, you can download actual files from the production website:
+
+.. code-block:: bash
+
+    # This will synchronize files on your local development server from your production server.
+    # Do not forget ending slash after each path!
+    rsync -avcz -e "ssh -p 22" user@my-prod-server.com:/path/to/roadiz/files/ /path/to/roadiz/files/
 
 
 Moving to a non-SSH hosting plan
@@ -66,21 +77,21 @@ an SFTP connection or worst, an old FTP one. Don’t panic, it will take a littl
 
 .. warning::
     Many shared-plan hosters offer you only one or two databases. When moving a Roadiz website, make sure
-    that your database is empty and do not contain orphan tables, you must respect the rule “One app = One database”.
-
-* Do not forget to generate ``.htaccess`` files for your prod server. Type ``bin/roadiz generate:htaccess``.
-* If you have at least SFTP, you should have to rights to zip/unzip on your distant server. So zip the whole Roadiz folder.
+    that your database is empty and do not contain orphan tables, you must respect the rule “One app = One database”.
 
 .. note::
     If you can ZIP on your production server or if you are going to push your files via FTP,
     do not forget to exclude ``.git`` and ``node_modules`` folders! These folders have **lots** of useless files
     for a production SSH-less environnement.
-    Here is a sample ZIP command to exclude them: ``zip -r mywebsite.zip mywebsite/ -x "mywebsite/.git/*" "mywebsite/themes/**/static/node_modules/*"``.
+    Here is a sample ZIP command to exclude them:
+    ``zip -r mywebsite.zip mywebsite/ -x "mywebsite/.git/*" "mywebsite/themes/**/static/node_modules/*"``.
 
+* Before transfering your website, make sure you have ``.htaccess`` file in every sensitive folders. You can use the ``bin/roadiz generate:htaccess`` on your computer.
+* If you have at least SFTP, you should have to rights to zip/unzip on your distant server. So zip the whole Roadiz folder.
 * If you only have FTP, you must be prepared to transfer your Roadiz folder, file-by-file. Just get yourself a nice cup of coffee.
 * Once everything is copied on your production server, verify than you have the same files as on your dev-server.
 * Import your database dump with phpmyadmin or pgmyadmin.
-* Edit your ``conf/config.yml`` to match your new database credentials. Enable ``devMode`` manually.
-* Verify that every sensitive folders contain an ``.htaccess`` file to deny access. Verify that root ``.htaccess`` file contains every informations to enable Apache url-rewriting.
-* Try to connect to your website, if everything works disable ``devMode`` and enjoy your hard work.
+* Edit your ``conf/config.yml`` to match your new database credentials.
+* Verify that root ``.htaccess`` file contains every informations to enable Apache url-rewriting.
+* Try to connect to your website
 * If it doesn’t work or display anything, read your PHP log file to understand where the problem comes from. It might be your database credentials or an oudated PHP version. Check that your hoster has installed every needed PHP extensions, see :ref:`requirements`.

developer/index.rst

@@ -14,4 +14,5 @@ skills.
    tags-system/index.rst
    themes/index.rst
    forms/index.rst
-   services/index.rst
+   services/index.rst
+   case-studies/index.rst

developer/themes/create_theme.rst

@@ -146,6 +146,8 @@ Then you will be able to add your fresh new theme into Roadiz backoffice.
 
 *We are planning a simple command-line tool that will ease up this process.*
 
+.. _theme_composer:
+
 Theme specific dependencies
 ---------------------------