Installation

Latest revision as of 07:55, 7 May 2024

DreamFactory is supported on Linux, Windows, and Mac OS X.

Get started with DreamFactory by following the installation instructions below. To get started select an install method and platform below.

GitHub

You can install DreamFactory directly from GitHub. We have provided platform specific instructions. If your desired platform is not available, you may need to modify the instructions presented herein.

Automated Installers

Automated installers for CentOS, Debian, Fedora, and Ubuntu are included in the GitHub repository. You can learn more about these installers here. These installers support both DreamFactory OSS and commercial versions.

Required Software and Extensions

At a minimum, you will need the following software and extensions installed and enabled on your system in order to successfully clone and install DreamFactory.

• PHP 7.4+ - check and install the requirements below for your particular environment.
  • PHP Migration guide
  • PHP required extensions: Curl, MBString, MongoDB, SQLite, and Zip. You may need to install other extensions depending upon DreamFactory usage requirements. If you don't plan on using MongoDB, please remove the df-mongodb requirement from composer.json, or include the --ignore-platform-reqs option when running composer install.
• Git - see https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
• A web server such as NGINX, Apache, or IIS. You may use PHP's built-in server for development purposes.
• One of four databases for storing configuration data: MS SQL Server, MySQL (MariaDB or Percona are also supported), PostgreSQL, or SQLite.
• Composer - see https://getcomposer.org/download/, may require cURL to be installed from particular environment below.

Operating system-specific instructions are available which may be useful if you need assistance satisfying these requirements:

• Linux
  • Mint, Debian or Ubuntu
  • CentOS and RedHat
• Mac
  • Mac OS X 10.11+
• Windows
  • Server 2012, Server 2016, Windows 10

Installing and Configuring DreamFactory

We strongly recommend using our automated installers. You can learn more about the installer here. If you'd like to install DreamFactory manually, use the instructions provided in this section. Keep in mind these instructions only pertain to installation of the DreamFactory software, and not to the installation of the many additional dependencies. Refer to the operating system-specific instructions found in this wiki for dependency-related details.

The commands shown below are primarily for a Linux/Unix-based operating system, but should also work on Windows (directory structure notwithstanding) provided all the required software and extensions are installed.

• Clone this repository to a directory on your system. For testing, using a directory under your home directory is easiest (and demonstrated here), otherwise choices like /var/www/ or /opt may be preferred.

$ git clone https://github.com/dreamfactorysoftware/dreamfactory.git ~/df2

• Change your working path to that directory.

$ cd ~/df2

• Install dependencies using Composer. If you're installing DreamFactory for use in a production environment, include the --no-dev option to avoid installing development-specific packages.

$ composer install --no-dev

• Next, you'll want to run the following two setup-related commands:

$ php artisan df:env
$ php artisan df:setup

• Note: In earlier versions of DreamFactory this command was named dreamfactory:setup or df:setup. As of DF 2.7.0 the command is changed to df:env

• Make sure your web server can read/write from/to the DreamFactory application's storage and bootstrap/cache directories. Unix/Linux and OSX users can use the chown and chmod commands to set these permissions:

$ sudo chown -R {www user}:{your user group} storage/ bootstrap/cache/
$ sudo chmod -R 2775 storage/ bootstrap/cache/

Set Up a Web Server

If you're just trying out DreamFactory, consider using PHP's built-in web server:

$ php artisan serve

Alternatively, you'll want to provision a web server by following these instructions:

Nginx

• Debian/Mint/Ubuntu
• CentOS/RedHat

Apache

• Debian/Mint/Ubuntu
• CentOS/RedHat

Set Up a Database

Additional drivers may be required if you plan on REST-enabling a database:

• SQLite
• MySQL, MariaDB, or Percona
• PostgreSQL
• Microsoft SQL Server
• SAP SQL Anywhere

Switching Your System Database

Your DreamFactory application manages many configuration details within an underlying database (four of which are supported: MySQL, MS SQL Server, PostgreSQL, and SQLite). If you want to change from one system database to another after you've already run setup/installation:

• Stop your web server
• Edit the .env file found in the DreamFactory application's root directory to define the correct driver, host, and port number. For example:

DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=dreamfactory
DB_USERNAME=dreamfactory
DB_PASSWORD=dreamfactory
DB_PORT=3306

• In your shell navigate to the DreamFactory application's root directory.
• Run these commands:

$ php artisan config:clear
$ php artisan cache:clear
$ php artisan df:setup

• Restart the web server

Docker Image

Two DreamFactory Docker images are available. The official image is maintained by our team and is available from df-docker repo on GitHub. A second image is maintained by Bitnami, and is available on DockerHub.

If you don't want to use Bitnami, you can still build your own docker image using our df-docker repo on GitHub.

PaaS Clouds

You can install DreamFactory on PaaS cloud platforms (Platform as a Service). Follow the instructions below.

• Red Hat OpenShift
• Pivotal using CloudFoundry
• IBM Bluemix using CloudFoundry

Raspberry Pi

You can install and configure DreamFactory on Raspberry Pi 2 as an open source IoT gateway. Follow the general instructions here.

Additional Drivers and Modules

• Apache Cassandra
• IBM Db2
• Microsoft SQL Server
• MySQL, MariaDB, or Percona
• MongoDB
• Node.js
• Oracle Database
• PostgreSQL
• SAP SQL Anywhere
• SQLite
• v8js

Installing DreamFactory Behind a Proxy

The DreamFactory installers rely upon several package managers to install not only the core platform software but also an array of dependencies critical to both the platform itself and the underlying operating system. In addition to using the Linux operating system's native installer (e.g. apt, yum, etc), examples of required third-party package managers and installation helpers include:

• curl
• pip
• pear

The installer scripts also reach out to GitHub to clone the DreamFactory OSS version (which can be upgraded to a commercial version as part of the installation process). Therefore, if you're running the server behind a proxy, you'll need to take some additional steps to account for the network restrictions, notably informing each package manager and installation helper of the proxy requirement.

Configuring curl

Create a file named .curlrc and add the following line to it:

proxy = 123.456.789:port

PECL/PEAR

Modify the installation script to include this line *after* PEAR and PECL have been installed:

pear config-set http_proxy http://123.456.789:port

PIP

Create the file ~/.config/pip/pip.conf and add this to it:

[global]
proxy = http://123.456.789:port

GitHub

Add the following code to your ~/.git/config file:

[http]
proxy = http://123.456.789:port

RPM

If your operating system uses the RPM package manager, you'll need to modify rpm statements to include the --httpproxy flag. For example:

sudo rpm --httpproxy http://123.456.789:port -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

Troubleshooting

If you receive the below error please follow these instructions.

GitHub API limit (60 calls/hr) is exhausted, could not fetch https://api.github.com/repos/dreamfactorysoftware/df-adldap. Create a GitHub OAuth token to go over the API rate limit. You can also wait until XXXX-XX-XX XX:XX:XX for the rate limit to reset.
 
Head to https://github.com/settings/tokens/new?scopes=repo&description=Composer to retrieve a token. It will be stored in "/root/.composer/auth.json" for future use by Composer.

First you will want to create a GitHub access token like so: https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line

After creating the access token and applying it via the command line, configure Composer to use your personal access token: https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line