Revision as of 15:21, 29 August 2016

DreamFactory instances use Git, Composer, and Artisan (a component of Laravel) to move from one version to another. Typically, this is for upgrading, though you could use this procedure to move to older versions of the software as well.

Important Notes (read before starting)

1. Windows users need to have Git shell for these procedures, such as Git for Windows
2. Install Directory
   • References to Install Directory or {install directory} refer to the top level directory that houses the actual DreamFactory code.
   • For manual installs this would be where you cloned the DreamFactory git repo, such as /opt/df2
   • For Bitnami installs this is the htdocs folder within the Bitnami installation. Here are the default locations for each operating system, where x.x.x-x represents the version and release number.
   • Unless otherwise noted all commands should be run from the install directory.
     • Linux: ~/dreamfactory-x.x.x-x/apps/dreamfactory/htdocs
     • Mac OS X: /Applications/dreamfactory-x.x.x-x/apps/dreamfactory/htdocs
     • Windows: /c/Bitnami/dreamfactory-x.x.x-d/apps/dreamfactory/htdocs
3. PHP
   • Commands that use the PHP executable can be completed two different ways depending on install type. For instance, if you are using the artisan migrate command. You will need to adjust the instructions below to fit your scenario.
   • For manual installs and Bitnami CLOUD images, PHP should be installed as a system command. You simply call it by name:

     $ php artisan migrate --seed

   • For Bitnami LOCAL installs, you must put the full path to the PHP executable file. The defaults for each OS are:
     • Linux:

       $ ~/dreamfactory-x.x.x-x/php/bin/php artisan migrate --seed

     • Mac OS X:

       $ /Applications/dreamfactory-x.x.x-x/php/bin/php artisan migrate --seed

     • Windows:

       $ /c/Bitnami/dreamfactory-x.x.x-d/php/php artisan migrate --seed

4. Composer
   • Commands that user Composer can be completed two different ways depending on install type. For instance, if you are performing composer install. You will need to adjust the instructions below to fit your scenario.
   • For manual installs, you likely installed composer as a system command:

     $ composer install --no-dev

   • For Bitnami installs, (or if you only installed the composer.phar file locally) you must use PHP to call composer:

     $ php composer.phar install --no-dev

Perform a Backup

1. Before upgrading or switching versions, you should make a backup of your environment.
2. Backup Files
   • In your shell, navigate to one level above the install directory.
   • Make a copy of the install directory.

     • $ cp -r {install directory} {install directory}.backup

   • In the unlikely event of a severe issue, you can restore this file backup.
3. Backup Database
   • Use your database tool of choice to make a complete backup of the database, such as phpMyAdmin, which comes packaged with the Bitnami installers.
   • In the unlikely event of a severe issue, you can restore this database backup.

Perform the Upgrade

1. Navigate to the install directory in your shell.
2. Make sure you've checked out the appropriate git tag.
   • If you're updating to the latest version, you'll checkout the master tag. If you're moving to a specific version number, you'll checkout that version number as the tag.

   • $ git checkout master

   • If you have unsaved changes, you'll receive a message indicating which files have changes in them. You will need to stash the changes.
     • You must do this step BEFORE checkout if you have made changes to or replaced any files in the main DreamFactory repo (such as changes to composer.json.)

     • $ git stash

     • Repeat the checkout step.
3. Pull the latest from git (again, using the appropriate tag -- master or version number).

   • $ git pull origin master

4. Reset permission on storage/ and bootstrap/cache/
   • Bitnami local installs can skip this step. Bitnami cloud images, VMs, and manual installs will typically need to perform this step.

   • $ sudo chown -R {web service user}:{your user group} storage/ bootstrap/cache/

   • $ sudo chmod -R 2775 storage/ bootstrap/cache/

5. Use Composer to update all the vendor repos.

   • $ composer install --no-dev

6. Migrate the database.

   • $ php artisan migrate --seed

7. If upgrading from DreamFactory 2.0 or 2.1 to DreamFactory 2.2 or higher, migrate the old service types to the new ones (add the --pretend option to see what it will change).

   • $ php artisan dreamfactory:service-type-migrate

8. Clear the application cache.

   • $ php artisan cache:clear

9. Restart your web server process.
   • For Bitnami local installs, use the Bitnami Manager app to restart Apache.
   • For Bitnami cloud and VMs, use the control script.

     • $ sudo ../../../ctlscript.sh restart

   • For manual installs, use your OS service management utility to restart Apache or PHP-FPM and Nginx (depending on which tool you're using).

Troubleshooting

It's possible that you may encounter some known issues when attempting to upgrade your instance. Below are a few known issues and how to fix them.

1. When attempting to run composer install --no-dev or any other php artisan command you get an error similar to this one: Script php artisan clear-compiled handling the post-install-cmd event returned with error code 1 and [Symfony\Component\Console\Exception\CommandNotFoundException] Command "migrate" is not defined.
   • 
   • 
   • Resolution
     • Navigate to the install directory.
     • Remove the compile cache and framework cache manually.

       • rm -rf bootstrap/cache/compiled.php storage/framework/cache/*

     • Resume the upgrade process. Begin by running the composer install step again.