Installation

Deployment Planning

There are a few things to consider before installing DreamFactory Enterprise (DFE). The rest of this section will explain these considerations.

It goes without saying that if you are simply evaluating DFE, on a single instance, server and DNS planning are unnecessary. Skip ahead to the Installer Utility section.

Minimum Requirements

DFE can be split out across multiple virtual machines or housed within a single one. The installer utility installs DFE as an **all-in-one** package. This requires a minimum of 7GB of RAM to function. 10-16GB is recommended.

Servers

DFE is a distributed system. Each component can operate and scale independently of each other. Conversely, the entire system can be contained on a single server. Therefore, the best server layout fully depends on your usage and needs. If you're just testing out DFE and not ready to deploy a production system, installing everything on a single server is the way to go (as it's mostly automated).

The servers required are:

• Application: Responsible for hosting/running the DFE Console, Dashboard, and/or the Reporting system.
• Database: Responsible for the databases of hosted instances
• Web: Responsible for (web) hosting the deployed instances

DNS

DFE operates each instance via virtual hosting on one or more web servers. As such, you must determine the fully qualified domain name of your DFE installation before installing. The system cannot be used fully until the DNS is in place. Generally, clients will create a new subdomain within their DNS domain. This is the recommended practice. Using a new domain will eliminate any issues with DNS cross-contamination if troubleshooting an issue.

There are three records that need to be created for the DFE installation. These are:

• console.sub.domain.com (A/CNAME)
• dashboard.sub.domain.com (A/CNAME)
• *.sub.domain.com (A/CNAME)

The first two are straightforward. These point to the DFE Console and Dashboard. These can be either A or CNAME records. The final record is the wildcard entry. This allows all instances deployed on a server to share a single, common document root. For more information on how to set up your DNS with a wildcard record, please consult your DNS provider's documentation. Each provider has a different method for creating these records.

Please note that you cannot add a wildcard DNS entry to your local /etc/hosts file. It does not work.

Automated Additions

One of the features of the installation system is that several entries will be added to the installation system's /etc/hosts file. Here is an /etc/hosts file after the installer has completed:

127.0.0.1   localhost ip-10-10-2-40 console console.local dashboard dashboard.local console.zone.domain.com dashboard.zone.domain.com zone.domain.com
 
::1	ip6-localhost	ip6-loopback
fe00::0	ip6-localnet
ff00::0	ip6-mcastprefix
ff02::1	ip6-allnodes
ff02::2	ip6-allrouters
ff02::3	ip6-allhosts

You'll notice after the localhost entry, there are seven additional entries which reference the new DFE installation. zone and domain are gathered via the installation utility and are used here for exemplary purposes.

Installer Utility

To help with installation, a utility may be downloaded and run. This utility gathers the necessary information that then feeds into the main installation system, which is written using Puppet. PHP is required to run this utility. To use this utility you must first install the required packages, which differs depending on your operating system.

For Debian/Ubuntu:

ubuntu@server:~ $ sudo apt-get update 
ubuntu@server:~ $ sudo apt-get upgrade
ubuntu@server:~ $ sudo apt-get install php5 puppet git

For Redhat/CentOS:

ubuntu@server:~ $ sudo yum update
ubuntu@server:~ $ sudo yum install php puppet git

Quick Look

Here's how to install the utility at a high level:

1. Update the system packages and install pre-requisites 2. Clone the utility's GitHub repository 3. Update composer dependencies 4. Start the installation utility 5. Open your browser and enter the configuration settings

Example:

ubuntu@server:~$ sudo apt-get update
ubuntu@server:~$ sudo apt-get upgrade
ubuntu@server:~$ sudo apt-get install php5 puppet git
ubuntu@server:~$ git clone https://github.com/dreamfactorysoftware/dfe-installer.git
ubuntu@server:~$ cd dfe-installer
ubuntu@server:~/dfe-installer$ php -S 0.0.0.0:8000 -t public/
^C

At this point, fire up your browser and enter the public IP address of the installation system as follows:

http://ip.of.install.machine:8000

Port 8000 is used in the above example. You may use any port you prefer. However, you must ensure that whichever port you choose (including 8000!) is open to your browser from wherever the server is hosted. This is a temporary usage, so there will be no need for permanent port changes.

Here's what you should see in your browser (I've updated my hosts file with the public IP so I don't have to use the IP address).

This utility has all the installation options available. Once completed, the entries are written to a file called .env-install in the storage directory the installation root. This file is then read by the ./install.sh script. This script does all the heavy lifting and completes the installation.

Once you've run the utility and created the installation environment file, you're ready to run the installation script.

To do this, from the root of the installation directory, run the following:

ubuntu@server:~/dfe-installer$ sudo ./install.sh

It can take up to 10 minutes to fully complete. This depends on your network connection and the server's specifications.

Complete Walk-Through

This is a complete walk through of the installation process with all information returned.

ubuntu@ip-10-10-2-233:~$ sudo apt-get -q=2 update 
ubuntu@ip-10-10-2-233:~$ sudo apt-get -q=2 -y upgrade
... # omitted/can vary
ubuntu@ip-10-10-2-233:~$ sudo apt-get -q -y install php5 git puppet
... # omitted/can vary
ubuntu@ip-10-10-2-233:~$ git clone https://github.com/dreamfactorysoftware/dfe-installer.git
Cloning into 'dfe-installer'...
remote: Counting objects: 8666, done.
remote: Compressing objects: 100% (84/84), done.
remote: Total 8666 (delta 20), reused 2 (delta 2), pack-reused 8578
Receiving objects: 100% (8666/8666), 9.65 MiB | 0 bytes/s, done.
Resolving deltas: 100% (2434/2434), done.
Checking connectivity... done.
ubuntu@ip-10-10-2-233:~$ cd dfe-installer/
ubuntu@ip-10-10-2-233:~/dfe-installer$ php -S 0.0.0.0:8000 -t public/
PHP 5.5.9-1ubuntu4.13 Development Server started at Wed Oct  7 23:51:19 2015
Listening on http://0.0.0.0:8000
Document root is /home/ubuntu/dfe-installer/public
Press Ctrl-C to quit.
[Wed Oct  7 23:51:57 2015] 76.97.26.128:45270 [200]: /
[Wed Oct  7 23:51:57 2015] 76.97.26.128:45271 [200]: /static/bootstrap-3.3.5/css/bootstrap.min.css
[Wed Oct  7 23:51:57 2015] 76.97.26.128:45273 [200]: /static/font-awesome-4.3.0/css/font-awesome.min.css
[Wed Oct  7 23:51:57 2015] 76.97.26.128:45272 [200]: /css/style.css
[Wed Oct  7 23:51:59 2015] 76.97.26.128:45254 [200]: /static/bootstrap-3.3.5/js/bootstrap.min.js
[Wed Oct  7 23:51:59 2015] 76.97.26.128:45255 [200]: /static/jquery-2.1.4/jquery.min.js
[Wed Oct  7 23:51:59 2015] 76.97.26.128:45276 [200]: /static/font-awesome-4.3.0/fonts/fontawesome-webfont.woff2?v=4.3.0
[Wed Oct  7 23:51:59 2015] 76.97.26.128:45256 [200]: /img/apple-touch-icon.png
[Wed Oct  7 23:51:59 2015] 76.97.26.128:45278 [404]: /public/img/apple-touch-icon.png - No such file or directory
[Wed Oct  7 23:52:34 2015] 76.97.26.128:45295 [302]: /
[Wed Oct  7 23:52:34 2015] 76.97.26.128:45297 [200]: /
[Wed Oct  7 23:52:34 2015] 76.97.26.128:45298 [200]: /static/font-awesome-4.3.0/css/font-awesome.min.css
[Wed Oct  7 23:52:34 2015] 76.97.26.128:45303 [200]: /static/bootstrap-3.3.5/css/bootstrap.min.css
[Wed Oct  7 23:52:34 2015] 76.97.26.128:45302 [200]: /css/style.css
[Wed Oct  7 23:52:34 2015] 76.97.26.128:45299 [200]: /static/jquery-2.1.4/jquery.min.js
[Wed Oct  7 23:52:34 2015] 76.97.26.128:45301 [200]: /img/apple-touch-icon.png
[Wed Oct  7 23:52:34 2015] 76.97.26.128:45300 [200]: /static/bootstrap-3.3.5/js/bootstrap.min.js
[Wed Oct  7 23:52:35 2015] 76.97.26.128:45304 [200]: /static/font-awesome-4.3.0/fonts/fontawesome-webfont.woff2?v=4.3.0
^C
ubuntu@ip-10-10-2-233:~/dfe-installer$ sudo ./install.sh 
********************************************************************************
* DreamFactory Enterprise(tm) Linux Installer v1.1.2
********************************************************************************

install.sh:	Checking system requirements...
install.sh:	   > Installed 6 required modules
install.sh:	Installing now...
install.sh:	Applying ./resources/assets/manifests/00-user.pp...
install.sh:	Applying ./resources/assets/manifests/10-filesystem.pp...
install.sh:	Applying ./resources/assets/manifests/20-percona.pp...
install.sh:	Applying ./resources/assets/manifests/30-packages.pp...
install.sh:	Applying ./resources/assets/manifests/40-dfe-console.pp...
install.sh:	Applying ./resources/assets/manifests/50-dfe-dashboard.pp...
install.sh:	Applying ./resources/assets/manifests/60-dfe-instance.pp...
install.sh:	Applying ./resources/assets/manifests/70-nginx_php-fpm.pp...
install.sh:	Complete! Output spooled to /tmp/dfe-installer.log
ubuntu@ip-10-10-2-233:~/dfe-installer$ 

All output of the installation utility is directed to a log file located at /tmp/dfe-installer.log. If there is an error, the log will detail the issue.

This log file is rotated each time install.sh is executed. The prior file is renamed to /tmp/dfe-installer.log. and a new empty file is created.

Post-Installation Steps

If you have already configured your DNS to point to the new installation, then you can skip this part entirely.

If you're setting up DFE on a single system, or with test/faux DNS entries, you *must* add these entries to your own /etc/hosts file.

First, you must locate the public, or accessible, IP address of the system upon which DFE is installed. Once you have that, simply add a line to the end of your /etc/hosts file:

public.ip.address.here    console.zone.domain.com dashboard.zone.domain.com zone.domain.com test1.zone.domain.com test2.zone.domain.com

Replacing **zone**, **domain** with the zone and domain used when installing the system. The final two entries are to map instances you create to your faux DNS. They allow you to create two instances (test1 and test2). You can change the name to whatever you prefer or add more entries. It's up to you.

Here's an actual example:

57.15.77.166    console.dfe.3wipes.com dashboard.dfe.3wipes.com dfe.3wipes.com leela.dfe.3wipes.com bender.dfe.3wipes.com fry.dfe.3wipes.com

The order of the hosts in the list is not important. However, the fact that they are separated by spaces, is.