Installation MacOS

Important Notes

This tutorial walks you through installing a web server stack (LAMP/LEMP) and assumes a more or less blank server. If you have existing resources installed on the server you will need to work around them. For example this tutorial assumes that DreamFactory will be the only/default web app on this server. If you have other sites (virtual hosts) you will need to adjust the configuration accordingly.

Prerequisites

DreamFactory requires certain applications for install and other functionality. Also, these instructions use Vim to edit files on the command line. If you are not familiar with vim you can get documentation here: Vim Documentation. You are also welcome to use any other text editor you prefer. Vim is not required.

1. git, curl, zip, and unzip are installed automatically with OS X 10.*
2. Install Homebrew

   • $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

3. Update Homebrew taps to include php (If using High Sierra this is not necessary, skip to the next section)

   • $ brew tap homebrew/dupes

   • $ brew tap homebrew/versions

   • $ brew tap homebrew/homebrew-php

PHP

These instructions will install PHP 7 with various modules. DreamFactory requires the mbstring, zip, curl, mongodb, and sqlite3 php modules. Additionally php-fpm is installed if you will be running Nginx as your web server (recommended.) Finally, the mysql php module needs to be installed if you will be using MySQL or MariadDB, which these instructions recommend for the system database. Other database types will require their php modules to be installed for use within DreamFactory. This is covered in the Drivers and Modules section.

Install for Apache

1. Install PHP and default modules with Brew

   • $ brew install php70 --with-apache --with-pear

   • $ brew install php70-mongodb

2. Start PHP and set it autostart on boot

   • $ brew services start php70

Install for Nginx

1. Install PHP and default modules with Brew

   • $ brew install php70 --with-fpm --with-pear

   • $ brew install php70-mongodb

2. Start PHP FPM and set it autostart on boot

   • $ brew services start php70

Composer

Composer is a PHP dependency manager and is required for installing DreamFactory.

1. Install Composer using Homebrew

   • $ brew install composer

Database

You'll need a database for the system to store configuration information. We recommend MariaDB for this. Other supported system databases are SQLite, PostgreSQL, and Microsoft SQL.

MariaDB

Install

1. Install MariaDB using Homebrew

   • $ brew install mariadb

2. Start the MariaDB service and set it to run on boot

   • $ brew services start mariadb

Setup

1. Login to the database

   • $ mysql -uroot

2. Create a database. You can name it whatever you like. Just make sure you save this information. For the example we called it dreamfactory.

   • CREATE DATABASE dreamfactory;

3. Create a user with all privileges on that database. You can name the user and password whatever you like. Just make sure you save this information. For the example we used dfadmin for both the user and the password.

   • GRANT ALL PRIVILEGES ON dreamfactory.* to 'dfadmin'@'localhost' IDENTIFIED BY 'dfadmin';

4. Flush privileges on the database and quit.

   • FLUSH PRIVILEGES;

   • quit

DreamFactory

Installing DreamFactory involves getting the required code via git and composer and then using the Laravel artisan command to set up the system. In these instructions, we will assume you are logged in as a user named dfuser. Anywhere you see this username substitute your own.

1. Create a directory for installation and make your user the owner of the directory. This will be the working directory for the remainder of this section.

   • $ mkdir /usr/local/var/dreamfactory

2. Navigate to the working directory and use git to clone the dreamfactory repo

   • $ cd /usr/local/var/dreamfactory

   • $ git clone https://github.com/dreamfactorysoftware/dreamfactory.git ./

3. Use composer to get dependencies
   • Note for commercial users: Copy your commercial license files into the working directory before running this command.

   • $ composer install --no-dev

4. Setup the DreamFactory system database connection
   • Note: Previously this command was dreamfactory:setup or df:setup. As of DF 2.7.0 the command is changed to df:env

   • $ php artisan df:env

     • Select option 1 for MySQL. Answer the onscreen prompts regarding database connection and credentials (which you set in the Database section.)
   • IMPORTANT. Before running the df:setup command again you need to edit the .env file.
     • Uncomment (remove the ##) the two lines that read ##DB_CHARSET=utf8 and ##DB_COLLATION=utf8_unicode_ci
     • Save the file

   • $ php artisan df:setup

     • Answer the onscreen prompts to create your first admin user for the system.
5. Clear the application cache

   • $ php artisan cache:clear

Web Server

DreamFactory relies on a web server application to serve the REST endpoints as well as the admin application to users. Options are Nginx and Apache.

Nginx

Installing Nginx in OS X with Homebrew defaults to port 8080. If you wish to use port 80, you will have to use sudo and provide additional configuration that is not covered in the scope of this document.

1. Install Nginx from Homebrew

   • $ brew install nginx

2. Start Nginx and set to autostart on boot

   • $ brew services start nginx

3. Navigate to the configuration directory

   • $ cd /usr/local/etc/nginx

4. Edit the config

   • $ vim nginx.conf

   • Find the section that starts with server {. You should edit this entire section so that it looks like this:

   • server {
         listen 8080 default_server;
     
         root /usr/local/var/dreamfactory/public;
         index index.php index.html index.htm;
     
         server_name localhost;
     
         gzip on;
         gzip_disable "msie6";
     
         gzip_vary on;
         gzip_proxied any;
         gzip_comp_level 6;
         gzip_buffers 16 8k;
         gzip_http_version 1.1;
         gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
     
         location / {
             include /usr/local/etc/nginx/conf.d/php-fpm;
             try_files $uri $uri/ /index.php?$args;
         }
     
         error_page 404 /404.html;
         error_page 500 502 503 504 /50x.html;
         location = /50x.html {
             root /usr/share/nginx/html;
         }
     }

   • Save and exit the file
5. Create and edit the php-fpm config for nginx

   • $ mkdir conf.d

   • $ vim conf.d/php-fpm

   • Edit this file so it looks like this:

   • location ~ \.php$ {
         try_files      $uri = 404;
         fastcgi_pass   127.0.0.1:9000;
         fastcgi_index  index.php;
         fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
         include        fastcgi_params;
     }

   • Save and exit the file