Upgrades

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.

New Instructions Available

In an effort to make the upgrade process easier we are providing the following system specific upgrade instructions

• Upgrading Manual Install on Ubuntu 16.04
• Upgrading Manual Install on Mac OS X (10.11)

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. Permissions
   • Bitnami Cloud images (AWS, Azure, etc.) need for commands to be run using sudo, since root owns all of the Bitnami installation directory
   • If the new code writes over the storage or bootstrap directories, you'll likely need to reset permissions. Use the info below when doing Perform the Upgrade step #9. The proper permissions are
     • For Bitnami Cloud images,

       root:daemon

     • For manual installs with Apache or Nginx
       • Debain based distros,

         www-data:{user who owns the parent directory}

       • RHEL based distros,

         apache:{user who owns the parent directory}

     • Bitnami local installers, this step shouldn't be necessary if you are performing the upgrade as the user who did the inital install.
4. 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

5. 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.
   • Note for commercial users: Copy your commercial license files into the working directory before running this command.

   • $ composer install --no-dev

6. Migrate the database.

   • $ php artisan migrate --seed

7. RARE CASE: 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. If the code pull wrote over storage or bootstrap directories, reset permissions

   • $ sudo chown -R {web server user}:{directory owner} storage/ bootstrap/cache/

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

10. 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.

1. When attempting to run $ ../../../php/bin/php composer.phar self-update command you get an error similar to this one: [Composer\Downloader\TransportException]The "https://getcomposer.org/versions" file could not be downloaded: php_network_getaddresses: getaddrinfo failed: nodename nor servname provided, or not known failed to open stream: php_network_getaddresses: getaddrinfo failed: nodename nor servname provided, or not known
   • "Resolution"
     • Check your connection and give the network a few minutes before running the command again.