--- title: "Installing and Configuring DreamFactory | DreamFactory" source: "https://guide.dreamfactory.com/docs/installing-and-configuring-dreamfactory/_print/" canonical_url: "https://guide.dreamfactory.com/docs/installing-and-configuring-dreamfactory/_print/" converted_at: "2026-04-04T15:06:03.092Z" format: "markdown" converted_by: "html-to-md-ai" --- This the multi-page printable view of this section. [Click here to print](#). [Return to the regular view of this page](/docs/installing-and-configuring-dreamfactory/). # Installing and Configuring DreamFactory Install DreamFactory on Linux, Docker, or Windows Server. Configure Apache, MySQL, SQL Server, Firebird, and environment settings. Self-hosted setup guide. - 1: [Install DreamFactory on Windows Server 2022 with IIS](#pg-66137d62aae6f5355fddf92e6907e5bd) # Installing and Configuring DreamFactory In this chapter you’ll learn how to install and configure DreamFactory. A number of installation solutions are available, including GitHub repository, point-and-click installers, Docker container, and cloud-specific installers. Be sure to carefully read through the set of options before making a decision, because some might be more suitable than others for your particular situation. ## Choosing a DreamFactory Version Regardless of whether you’d like to spin up a DreamFactory instance on your local laptop, within a cloud environment such as AWS or Google Cloud, or Docker, we have a ready-made solution for you! ### The DreamFactory GitHub Repository Cloning DreamFactory’s OSS repository has long been by far the most popular way to access the software. To clone the repository you’ll need to install a Git client on your local machine or a server, at which point you can clone it using the following command: ``` $ git clone https://github.com/dreamfactorysoftware/dreamfactory/ ``` DreamFactory is built atop the very popular [Laravel Framework](https://www.laravel.com), which is in turn built atop PHP. This means DreamFactory is almost ubiquitously supported in all hosting environments; you’ll just need to make sure your hosting environment is running PHP 8.1 or greater, a recent version of a web server such as Apache or NGINX, access to one of four databases for storing configuration data (MySQL/MariaDB, PostgreSQL, SQLite, and MS SQL Server are supported), and that you have adequate permissions to install a few requisite PHP extensions. You can learn more about the required software and extensions via our wiki: [https://wiki.dreamfactory.com/DreamFactory/Installation#GitHub](https://wiki.dreamfactory.com/DreamFactory/Installation#GitHub) ### Docker Our Docker container is increasingly popular, and includes everything you need to run DreamFactory including Ubuntu 22.04, PHP 8.1, and the NGINX web server. It also includes all of the required PHP extensions, meaning you should be able to begin experimenting with the latest DreamFactory version as quickly as you can spin up the container! To learn more about the container, head over to our df-docker repository: [https://github.com/dreamfactorysoftware/df-docker](https://github.com/dreamfactorysoftware/df-docker) ### Bitnami Many users simply want to evaluate DreamFactory without putting any time or effort whatsoever into procuring a test server or fiddling with configuration issues. If you fall into this category then our Bitnami point-and-click installers are for you! These virtual machines include everything you need to begin running DreamFactory, and include a built-in database server, web server, PHP runtime, and a bunch of other useful software. Installers are available for Linux, Windows, and Mac OS X. Download your desired version via the following link: [https://www.dreamfactory.com/downloads](https://www.dreamfactory.com/downloads) If you’re using DreamFactory’s commercial Bitnami edition and would like to configure Oracle, follow these instructions: - [Configuring Oracle with Bitnami](./#using-the-bitnami-installers) ### Cloud Images Cloud environments are the hosting solution of choice these days, and for good reason. Cloud service providers offer unsurpassed levels of stability, performance, and security, and countless additional features capable of maximizing IT teams' efficiency while minimizing costs. DreamFactory offers Bitnami images targeting all of the major cloud providers, including AWS, Azure, Google, and Oracle Cloud. Download your desired version via the following link: [https://www.dreamfactory.com/downloads](https://www.dreamfactory.com/downloads) ## Using the DreamFactory Installer By far the simplest method of installing DreamFactory on Linux is by using our installer which can be found [here](https://github.com/dreamfactorysoftware/dreamfactory/blob/master/installers/dfsetup.run). The installer will determine your OS, and install all the necessary packages that DreamFactory requires to run, as well as a webserver (Nginx or Apache), and DreamFactory itself. To start we will download our installer `dfsetup.run`. You can do so either directly from the [GitHub page](https://github.com/dreamfactorysoftware/dreamfactory/blob/master/installers/dfsetup.run) and clicking download, or with wget: ``` wget https://github.com/dreamfactorysoftware/dreamfactory/raw/master/installers/dfsetup.run ``` Now that we have the script on our server, let’s make it executable. ``` chmod +x dfsetup.run ``` Now we can run the script! ``` sudo ./dfsetup.run ``` You will be greeted by an interactive menu, where if you wish you can choose additional installation options (such as with an Apache webserver) by pressing the corresponding number. ![DreamFactory Installer Options](/images/02/install-script.png) A default installation (0) will install the Nginx web server, DreamFactory, and the required system and PHP extensions, but will **not install a database server** (unless you choose sqlite as your database). To see a full list of installation options check it our [here](https://github.com/dreamfactorysoftware/dreamfactory/tree/master/installers#installation-options). If you select option 5, then the installer will also setup a MySql Database to be used as the system database. After choosing your additional options (if any), hit enter and the installer will go about getting everything ready. Fill out any prompts and then upon completion you can now go to your browser and access your instance! ## Installing and Configuring DreamFactory from Source If you’ve cloned the GitHub repository, you’ll need to carry out a few additional steps before launching your DreamFactory instance. The first step involves ensuring your server requirements have been met. Let’s tackle those first, followed by an overview of software installation. ### Configuring Your Server This guide is under heavy development, and certain parts are incomplete. We suggest reading through the current installation documentation, [available here](https://wiki.dreamfactory.com/DreamFactory/Installation#GitHub). Server configuration is going to vary according to your operating system. To ensure the instructions are as specific and straightforward as possible, we’ve broken them out into subchapters: - [Debian / Ubuntu](./#configuring-your-ubuntu-server) If you plan on using PHP in conjunction with one of the following databases, please review the pertinent subchapters presented below: - [Microsoft SQL Server](./#configuring-microsoft-sql-server-for-dreamfactory) - [SAP SQL Anywhere](./#configuring-sap-sql-anywhere) - [Firebird](./#configuring-firebird-for-dreamfactory) If you plan on running scheduled tasks, please make sure that crond is installed and running on your OS. You can check with `systemctl status crond`, start with `systemctl start crond`, and enable it (so it starts up on boot) with `systemctl enable crond`. If you do not have it installed, you can do so from your package manager (`cronie` on RHEL systems and `cron` on debian systems). ### Server Hardware Requirements DreamFactory is surprisingly performant even under minimally provisioned servers, you’ll want to install DreamFactory on a 64-bit server with at least 4GB RAM. If you’re planning on hosting the system database on the same server as DreamFactory, then we recommend at least 8GB RAM. This server will house not only the operating system and DreamFactory, but also a web server such as Nginx (recommended) or Apache, and PHP-FPM. Keep in mind these are the *minimum* RAM requirements; many customers can and do run DreamFactory in far larger production environments. Under heavier loads you’ll want to load balance DreamFactory across multiple servers, and take advantage of a shared caching (Redis or Memcached are typically used) and database layer (which houses the system database). Cloud Environment Minimum Server AWS t2.large Azure D2 v3 Oracle Cloud VM.Standard.E2.1 Digital Ocean Standard 8/160/5 Google Cloud n1-standard-2 Although DreamFactory can run on Windows Server and IIS, we recommend instead using a popular Linux distribution such as Ubuntu, Debian, or CentOS in order to take advantage of our automated installers targeting those specific operating systems. Prior to launching your project, we recommend thoroughly testing your APIs under estimated production loads using a tool such as [loader.io](https://loader.io/). ### Installing DreamFactory The first step involves installing the required PHP packages using Composer: ``` $ composer install --no-dev ``` The `--no-dev` option tells Composer to not install the development-specific dependencies. These development dependencies are used by our OSS community and internal developers alike to assist in software development. You can review the list of both required and developmental dependencies by opening the `composer.json` file found in the project’s root directory. If you receive an error regarding `Your requirements could not be resolved to an installable set of packages`, and you don’t require MongoDB, then you can quickly hurdle the issue by additionally supplying the `--ignore-platform-reqs` option when running Composer. With the packages installed, you’ll next need to configure your system database. This database will house various configuration settings associated with your instance. DreamFactory supports four databases for this purpose, including Microsoft SQL Server, MySQL, PostgreSQL, and SQLite. Keep in mind you’ll need to first create this database along with an account DreamFactory will use to connect to it. #### Example: PostgreSQL Once you have a PostgreSQL instance setup and the server running, you will need to create a user (“Role”) for DreamFactory to login with, and a database to use. The simplest was to do so is to first switch over to the `postgres` user that will automatically have been created upon installation of PostgresSQL: ``` sudo -i -u postgres ``` Now open up `psql` and create your new Role and Database for DreamFactory to use. (Note that If you are connecting remotely to your database server you can use `psql -h -U -p 5432` to directly get into psql): ``` CREATE ROLE dfadmin LOGIN PASSWORD 'pghwosfg78'; CREATE DATABASE dreamfactory ``` **Note** The user must, at the very least, have LOGIN privileges Finally, its best to double check that PostgreSQL is setup to accept IPv6 connections using md5 (i.e password) login. Go to your `pg_hba.conf` file and check (or amend as necessary) you have something along the lines of the following: ``` host all all ::1/128 md5 ``` You’ll configure the system database by running a terminal command and answering a few prompts about your database configuration. To do so, run the following command from inside your project’s root directory: ``` $ php artisan df:env ************************************************** * Configuring DreamFactory... ************************************************** Created .env file with default configuration. Created phpunit.xml with default configuration. Which database would you like to use for system tables? [sqlite]: [0] sqlite [1] mysql [2] pgsql [3] sqlsrv > 1 Enter your mysql Host: > 192.168.10.10 Enter your Database Port [3306]: > Enter your database name: > dreamfactory Enter your database username: > dreamfactory_user Enter your database password: > Re-enter your database password: > CACHE DRIVER is not supported. Using default driver file. Configuration complete! ************************* WARNING! ************************** * * Please take a moment to review the .env file. You can make any * changes as necessary there. * * Please run "php artisan df:setup" to complete the setup process. * ************************************************************* ``` With the system database configured, it’s time to create the system tables and seed data and then create your first system administrator account. This is accomplished by running the `df:setup` command. Because multiple prompts are involved with this command, I’ll break the command output into a few parts. Immediately after running `df:setup`, the command will create the database tables and seed data: ``` $ php artisan df:setup ********************************************* * Welcome to DreamFactory Setup. ********************************************* Running Migrations... Migration table created successfully. Migration driver used: sqlite Migrating: 2015_01_27_190908_create_system_tables Migrated: 2015_01_27_190908_create_system_tables Migrating: 2015_01_27_190909_create_db_extras_tables Migrated: 2015_01_27_190909_create_db_extras_tables ... Migration completed successfully. ********************************************* ********************************************* Running Seeder... Seeding: AppSeeder App resources created: admin, api_docs, file_manager Seeding: EmailTemplateSeeder Email Template resources created: User Invite Default, User Registration Default, Password Reset Default Service resources created: system, api_docs, files, logs, db, email System service updated. Service resources created: user All tables were seeded successfully. ``` Next you’ll be prompted to create your first system administration account: ``` Creating the first admin user... Enter your first name: > Jason Enter your last name: > Gilmore Enter your email address?: > [email protected] Choose a password: > Re-enter password: > Successfully created first admin user. ``` Finally, you’ll be prompted to make sure your application’s `storage` and `bootstrap/cache` directories are properly configured. This involves making sure the directory ownership and permissions are properly set using the `chown` and `chmod` commands: ``` * Please make sure following directories and all directories under * them are readable and writable by your web server * -> storage/ * -> bootstrap/cache/ * Example: * > sudo chown -R {www user}:{your user group} storage/ bootstrap/cache/ * > sudo chmod -R 2775 storage/ bootstrap/cache/ ``` The `{www user}` string is a placeholder for the owner of your web server daemon owner. The `{your user group}` string is a placeholder for the web server group daemon owner. Immediately following this prompt you’ll be informed of successful setup: ``` ********************************************************** ******************** Setup Successful! ******************* ********************************************************** * Setup is complete! Your instance is ready. Please launch * your instance using a browser. You can run "php artisan serve" * to try out your instance without setting up a web server. ********************************************************** ``` If you’ve installed and configured DreamFactory to run on a web server, then you can open your browser and navigate to the IP address or domain name. Otherwise, if you haven’t yet installed a web server, you can run `php artisan serve`: ``` $ php artisan serve Laravel development server started: ``` This will start a simple PHP server running on `127.0.0.1` port `8000`. Open your browser and navigate to `http://127.0.0.1:8000` and you should see the following screen: ![DreamFactory Login Screen](/images/02/first_boot.png) ### Using an Encrypted System Database By default, credential fields (such as passwords) stored in the DreamFactory system database will be encrypted. In addition, DreamFactory is more than happy to use a fully-encrypted database as an additional security layer. In this section you will find a basic tutorial to setup and configure MySQL (we will use MariaDB) for Data-At-Rest Encryption: 1. Before installing DreamFactory, we will want to install MariaDB onto the server using the following commands: ``` sudo apt update -y sudo apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 0xF1656F24C74CD1D8 add-apt-repository 'deb [arch=amd64,arm64,ppc64el] http://nyc2.mirrors.digitalocean.com/mariadb/repo/10.3/ubuntu focal main' sudo apt install mariadb-server ``` 1. Next, we will generate some random encryption keys using `openssl rand` (in this case, five of them): ``` mkdir /etc/mysql/encryption for i in {1..5}; do openssl rand -hex 32 >> /etc/mysql/encryption/keyfile; done; ``` 1. Now, open the keyfile in `/etc/mysql/encryption/keyfile` with your preferred text editor and add some key ids. For the sake of simplicity in this tutorial, they will just be from one to five. The ids will be added before the start of each our hex encoded keys, followed by a semi-colon. You will end up with something looking like this: ``` 1;e29c31c9b8e0386fe19409098ab7b3e54e11fb20ed0793e3e0a956e17f375562 2;114da537ee5dbea27503b96ba499012c9a554e9f01aadc419b8e35315600c7b6 3;8c6cd07eb38f5ecfacd16415449246f78d9b9252fa35dec3e9758e8f9b11a778 4;37109443404ac12d6a20f11df11dd2611aa6b399e1d66fa70284e202096d45d4 5;53379594cfe6073e88dbcf55edf65968ffb4c2fb5c64c171755f700a38e073e3 ``` 1. Generate a random password using the same `openssl rand` command: ``` openssl rand -hex 128 > /etc/mysql/encryption/keyfile.key ``` 1. and encrypt the keyfile ``` openssl enc -aes-256-cbc -md sha1 -pass file:/etc/mysql/encryption/keyfile.key -in /etc/mysql/encryption/keyfile -out /etc/mysql/encryption/keyfile.enc ``` Our encyption folder should now contain a `keyfile`, `keyfile.enc`, and `keyfile.key` files. 1. We will add the following variables to the mysql configuration file, which can be found in `/etc/mysql/my.cnf`. These should be added in the daemon section, i.e `[mysqld]`: ``` [mysqld] ... plugin_load_add = file_key_management file_key_management_filename = /etc/mysql/encryption/keyfile.enc file_key_management_filekey = FILE:/etc/mysql/encryption/keyfile.key file_key_management_encryption_algorithm = aes_cbc encrypt_binlog = 1 innodb_encrypt_tables = ON innodb_encrypt_log = ON innodb_encryption_threads = 4 innodb_encryption_rotate_key_age = 0 # Do not rotate key innodb_encrypt_tables = FORCE ``` The last variable `innodb_encrypt_tables = FORCE` will make all tables encrypted. Then start up mysql with `systemctl start mysql`. 1. Now we will install DreamFactory. If using the installer, you can select option 5 at the start, and it will detect that mysql is already running. It will prompt you for the root password, and then create the database and the DreamFactory user on your behalf. ![Setting the MySQL Root Password](/images/02/configure_mysql_database.png) Alternatively, if using `php artisan df:env`, or not selecting option 5 with the installer, you may create a database and a user beforehand (e.g a database named `dreamfactory` and a user called `dfadmin` with privileges to that that database). The installer, (or running `php artisan df:env`) will then prompt you for those details: ![Setting the System Database](/images/02/database_prompt.png) The installation will then complete, ask you for the first user, and you will have an encrypted system database. This can be tested and confirmed by logging into the MySQL cli and running the following command: ``` select * from information_schema.innodb_tablespaces_encryption; ``` which will return something similar to the following: ![Listing Encrypted Tables in MySQL](/images/02/encrypted_tables.png) We can also grep the tables using `strings` for, e.g., the first user we just created with the following: ``` strings /var/lib/mysql/dreamfactory/user.ibd | grep "" ``` and you will note that it returns empty. ## Introducing the .env File It is often helpful to have different configuration values based on the environment where the application is running. For example, you may wish to use a different cache driver locally than you do on your production server. To make this a cinch, Laravel utilizes the [DotEnv](https://github.com/vlucas/phpdotenv) PHP library by Vance Lucas. In a fresh Laravel installation, the root directory of your application will contain a `.env.example` file. If you install Laravel via Composer, this file will automatically be renamed to `.env`. Otherwise, you should rename the file manually. For more information, please see the [official Laravel documentation](https://laravel.com/docs/5.5/configuration#environment-configuration) ### Enabling Debugging and Logging By default, DreamFactory does not enable debugging due to performance issues. However, it can easily be enabled. In the example `.env` file below you can see where these options live. ```php ##============================================================================== # Environment Settings ##============================================================================== # Use the installer.sh file in this directory to easily edit these settings. # By default each setting is set to its internal default and commented out. ##------------------------------------------------------------------------------ # Application Settings ##------------------------------------------------------------------------------ # Application name used in email templates and other displays #APP_NAME=DreamFactory # Encryption cipher options are AES-128-CBC or AES-256-CBC (default) #APP_CIPHER=AES-256-CBC # Return debugging trace in exceptions: true or false (default) #APP_DEBUG=false # Environment this installation is running in: local, production (default) APP_ENV=local # Use 'php artisan key:generate' to generate a new key. Key size must be 16, 24 or 32. APP_KEY=base64:YOUR_APP_KEY #APP_LOCALE=en # LOG setting. Where and/or how the log file is setup. Options are single (default), daily, syslog, errorlog APP_LOG=daily # LOG Level. This is hierarchical and goes in the following order. # DEBUG -> INFO -> NOTICE -> WARNING -> ERROR -> CRITICAL -> ALERT -> EMERGENCY # If you set log level to WARNING then all WARNING, ERROR, CRITICAL, ALERT, and EMERGENCY # will be logged. Setting log level to DEBUG will log everything. APP_LOG_LEVEL=debug # When APP_LOG is set to 'daily', this setting dictates how many log files to keep. APP_LOG_MAX_FILES=5 # PHP Date and Time function timezone setting #APP_TIMEZONE=UTC # External URL representing this install #APP_URL=http://127.0.0.1:8000 # The starting point (page, application, etc.) when a browser points to the server root URL, #DF_LANDING_PAGE=/dreamfactory/dist/index.html DF_LICENSE_KEY=YOUR_LICENSE_KEY ``` When working to get your environment up and running, DreamFactory recommends turning debugging on, as well as increasing the sensitivity of the logging environment. In order to turn the application debugging on, please uncomment and change the following value: ```php APP_DEBUG=true ``` To modify your logging values you will need to uncomment and modify the following snippets of code: ```php APP_LOG=daily APP_LOG_LEVEL=debug APP_LOG_MAX_FILES=5 ``` ### Enabling Email Registration When creating new users and admins it is not ideal nor secure to manually set a password for each one. You can instead enable email registration which will allow you to instead send e-mail invitations by checking the `Send email invite` option. This will send an email invite to the new user containing a link to your instance and allow them to set a password. To enable e-mail support, you will need to add the below lines to your `.env` file and then you can send new users registration notifications! ``` MAIL_DRIVER=smtp MAIL_HOST=smtp.gmail.com MAIL_PORT=587 [email protected] MAIL_PASSWORD=YOUR_PASSWORD ``` Keep in mind `smtp` is but one of several available delivery options. ### Increasing Your Session Lifetime For security reasons DreamFactory sessions are limited to 60 minutes. You can however change the lifetime to any desired duration by opening your `.env` file and finding the following variable: ``` #DF_JWT_TTL=60 ``` Change `DF_JWT_TTL` to any duration you please, defined in minutes. For instance, the following settings will persist your session for a week: ``` DF_JWT_TTL=10080 ``` ## Updating Your DreamFactory Docker Environment Our DreamFactory environment is still a work-in-progress, however many users are actively using it thanks to Docker’s streamlined configuration and deployment options. Occasionally you’ll want to update to a newer version of DreamFactory so we’ve assembled the following instructions as a guide. You are presumably reading this section with the intention of upgrading a DreamFactory production environment. As with any software, things can and do go wrong with upgrading production environments, and therefore you are urged to possess a readily accessible file and system database backup and recovery plan before attempting an upgrade. You have been warned! Begin by opening a terminal and entering your DreamFactory instance’s root directory. Then execute this command: ``` $ docker-compose exec web cat .env | grep APP_KEY APP_KEY=base64:U/En8zI8WKrZ/F7CA9KncWjGTIhbvpGD5wN3eLoDZuQ= ... ``` A couple of lines of output will be returned, however you should only copy the line beginning with `APP_KEY` into a text file. Keep in mind at a *minimum* you’ll need to copy down the `APP_KEY` value. If you’ve overridden other defaults, such as the type, location, and credentials associated with the system database, you’ll need to copy those too. It is very important you perform this step otherwise you’ll run into all sorts of upgrade-related issues. Next, run the following command: ``` $ git tag --list 2.1 2.14.1 2.2 2.2.1 ... ``` This displays all of the tagged versions. Begin by stopping the running DreamFactory container without deleting it. Keep in mind that when you run this command, your DreamFactory instance will go offline until the upgrade process is completed: ``` $ docker-compose stop Stopping df-docker_web_1 ... done Stopping df-docker_mysql_1 ... done Stopping df-docker_redis_1 ... done ``` For the purposes of this example we’ll presume you’re running 2.12 and want to upgrade to 2.14.1. To do so you’ll first want to checkout the 2.14.1 tag: ``` $ git checkout tags/2.14.1 ``` Next, you’ll need to add that `APP_KEY` to the `docker-compose.yml` file. Open `docker-compose.yml` in your code editor, scroll down to the `web` service, and add the `APP_KEY` property and associated value alongside the other environment variables: ``` ... DB_DATABASE: dreamfactory APP_KEY: 'base64:U\/En8zI8WKrZ\/F7CA9KncWjGTIhbvpGD5wN3eLoDZuQ=' CACHE_DRIVER: redis ... ``` It is crucial that you encapsulate the `APP_KEY` value within single quotes, and additionally escape with a backslash any forward slashes appearing in your key! As an example, compare the `APP_KEY` entry found above with the output displayed earlier. Save these changes, and then rebuild your container using the following command: ``` $ docker-compose up -d --build ``` Once complete, you can run the following command to confirm the containers are up and running: ``` $ docker-compose ps Name Command State Ports -------------------------------------------------------------------------------- df-docker_mysql_1 docker-entrypoint.sh mysqld Up 3306/tcp, 33060/tcp df-docker_redis_1 docker-entrypoint.sh redis ... Up 6379/tcp df-docker_web_1 /docker-entrypoint.sh Up 0.0.0.0:80->80/tcp ``` If something has gone wrong, and one of the containers indicates it has exited, you can view the logs for that container: ``` $ docker-compose logs web ``` Presuming the containers are up and running, you’ll next want to determine whether the DreamFactory system database schema has changed. To do so run this command: ``` $ docker-compose exec web php artisan migrate:status ``` If you see `Y` in the tabular output’s `Ran?` column, then the schema has not changed. If you see `N` at any point, then you’ll need to run the following command to update your system database schema: ``` $ docker-compose exec web php artisan migrate ``` Finally, you’ll want to clear your application and configuration caches by executing the following commands: ``` $ docker-compose exec web php artisan config:clear Configuration cache cleared! $ docker-compose exec web php artisan cache:clear Cache cleared successfully. ``` With that done, open your DreamFactory instance in the browser, and confirm the environment is operational. ## Installing and Configuring DreamFactory on CentOS First pull in the CentOS Docker image. ``` $ docker pull centos ``` Then I start the image in a detached state. ``` $ docker run -itd {Container_ID} ``` Once the image is running we can enter it and begin installing DreamFactory. ``` $ docker exec -it {Container_ID} /bin/bash ``` From here, rather than copying and pasting a lengthy list of commands, we can use the DreamFactory Installer as described [above](./#using-the-dreamfactory-installer). ``` wget https://github.com/dreamfactorysoftware/dreamfactory/raw/master/installers/dfsetup.run chmod +x dfsetup.run sudo ./dfsetup.run ``` ## Choosing an HTTP Client Whether your API consumer is an iPhone or Android application, a SPA (Single Page Application), or another server altogether, that consumer is often referred to as the *client*. The client issues HTTP requests to the REST API, parsing the responses and reacting accordingly. Although in most cases your team will use libraries such as [Alamofire](https://github.com/Alamofire/Alamofire) or [Axios](https://github.com/axios/axios) to manage these requests, you’ll often want to interact with the APIs in a much more fluid manner during the investigatory and learning phase. The API Docs feature serves this need well, however the API Docs interface lacks the ability to bookmark and otherwise persist queries, manage parameters programmatically using variables, and other features useful for maintaining a set of easily accessible configurations. Fortunately, there are a number of HTTP clients which fill this void very well. Two of the most popular are [Insomnia](https://insomnia.rest/) and [Postman](https://www.getpostman.com/), which are available on OSX and multiple operating systems, respectively. In this section we’ll introduce you to both HTTP clients, and as an added bonus talk about the ubiquitous cURL client which is quite possibly the most popular piece of software you’ve never heard of. ### Insomnia [Insomnia](https://insomnia.rest) is a cross-platform REST client, built on top of [Electron](https://electronjs.org/). Insomnia is realtively new on the scene compared to cURL and Postman but offers a bevy of features that certainly make it competitive. They have a very slick UI, and a ton of features, including a team option. ![Insomnia UI](/images/02/insomnia.png) ### Postman [Postman](https://www.getpostman.com) is a tried and true GUI interface with great docs to help you set up your testing environment. They have plans for everyone, from free solo users to large, enterprise teams. Postman also has a great feature called [API Network](https://www.getpostman.com/api-network/), which has sample API calls from all sorts of sources. It is definitely worth a look. ![Postman UI](/images/02/postman1.png) ### cURL [cURL’s](https://curl.haxx.se/) lack of a polished interface may lead you to believe it’s inferior to Insomnia and Postman. Not so! cURL is an incomparably capable bit of software. cURL is a command line tool and library for transferring data with URL syntax, supporting HTTP, HTTPS, FTP, FTPS, GOPHER, TFTP, SCP, SFTP, SMB, TELNET, DICT, LDAP, LDAPS, FILE, IMAP, SMTP, POP3, RTSP and RTMP. ## Running DreamFactory in a High Availability, Load Balanced Environment Most high API volume request users are running DreamFactory in a highly-available, load balanced environment. The following diagram depicts this approach: ![DreamFactory Load Balanced HA Environment](/images/02/lb-ha-diagram.png) If you’re not interested in running the DreamFactory platform itself in an HA cluster then disregard the “Secondary Environment” found in the “DreamFactory Application Cluster” tier however the remainder of the diagram would still apply in a purely load balanced environment. In either case, the load balanced DreamFactory instances would be backed by a caching and system database tier. For caching DreamFactory supports Memcached and Redis. On the system database side, DreamFactory supports MySQL, PostgreSQL, and Microsoft SQL Server. --- ## Using the Bitnami Installers These instructions are for configuring the drivers to work with DreamFactory’s commercial Bitnami edition. ### Bitnami Linux Oracle To begin, follow steps 1-3 found in this section of the Bitnami documentation: - [Bitnami documentation](https://docs.bitnami.com/installer/apps/dreamfactory/administration/configure-db/) Once that’s done, you’ll want to complete one more step. SSH into the server where your DreamFactory Bitnami installation is hosted, and navigate to the `/php/bin` directory found inside the installation directory. For reference purposes, we’ll use the `INSTALL_DIR` placeholder to refer to this directory/ ``` $ cd /INSTALL_DIR/php/bin ``` Next, run the following command, making sure you prefix the `php` command with `./`: ``` $ ./php --ini ``` In the output you will see the following line: ``` Loaded Configuration File => /opt/dreamfactorygold-3.0.1-0/php/etc/php.ini ``` The value of `Loaded Configuration File` identifies the location of Bitnami’s `php.ini` configuration file. Keep in mind your path might be different from the example presented above. Open this `php.ini` file with a text editor and search for this line: ``` ;extension=oci8.so ``` Uncomment it by removing the semicolon and save the changes. Now restart Bitnami’s Apache server: ``` $ cd /INSTALL_DIR/ $ ./ctlscript restart apache ``` Once restarted your DreamFactory Bitnami instance is capable of connecting to an database. After configuring a new API using DreamFactory’s service connector, head over to the `API Docs` tab to confirm you can connect to the database. One of the easiest ways to do so is by executing the following endpoint: ``` GET /_table Retrieve one or more Tables. ``` Executing this endpoint will result in a list of tables being returned from the connected database. --- ## Configuring Firebird for DreamFactory These instructions are for installing the Firebird driver from its [source code](https://github.com/php/pecl-database-interbase). ### Install the Firebird driver ``` cd /tmp git clone https://github.com/php/pecl-database-interbase.git cd pecl-database-interbase/ apt-get install firebird-dev autoconf build-essential phpize --clean phpize ./configure make make install ``` Once downloaded, you will want to enable the driver in your php.ini file. After that, the extension will appear in the list of enabled extensions. ``` php -m [PHP Modules] ``` ### Troubleshooting If you receive a 500 error with the message of `The Response content must be a string or object`, make sure your database is configured for UTF8. --- ## Configuring Microsoft SQL Server for DreamFactory on Windows Install both Microsoft ODBC Drivers [17](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16) and [18](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16#version-17). Download [SQL Server driver](https://github.com/microsoft/msphpsql/releases/download/v5.11.0/Windows-8.1.zip) package. Unpack downloaded `.zip` and move files `php_sqlsrv_81_nts.dll` , `php_pdo_sqlsrv_81_nts.dll` to your PHP extension directory. Get rid of the `_81_nts` sufix in both file names. **Note:** To determine whether your installed version of PHP is thread-safe or not, you can execute the following command in your command prompt or terminal: ``` php -i|findstr "Thread" ``` This command will return one of the following lines: - Thread Safety => enabled: This means that your PHP installation is thread-safe. - Thread Safety => disabled: This means that your PHP installation is not thread-safe. In your `php.ini` file add next lines: ``` extension=php_sqlsrv.dll extension=php_pdo_sqlsrv.dll ``` Lastly, in case of running PHP on a web server, it is recommended to restart the server. Afterwards, use the command php -m to retrieve a list of installed modules, and search for sqlsrv and pdo_sqlsrv within the list. ## Installing DreamFactory on Windows Server with IIS10 **Note:** These installation instructions assume a “Clean Install” for IIS. There may be sections which have already been accomplished or installed. If so, skip the sections which no longer apply to your situation. These instructions are concerned only with the installation of DreamFactory. Please consult your Windows Administrator for [hardening the web server and other security controls](https://msdn.microsoft.com/en-us/library/ff648653.aspx) which are outside the scope of these instructions. ### Installing DreamFactory on Windows Server 2022 with IIS10 Instructions can be found [here](./A-Installing-DreamFactory-on-Windows-Server/) ### *Install PHP for IIS* Before proceeding, ensure that you have installed Visual C++ Redistributable. The download link can be found in the [official documentation](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022) provided by Microsoft. It is unfortunate that the Web Platform Installer [has been retired](https://blogs.iis.net/iisteam/web-platform-installer-end-of-support-feed). However, there is no need to worry as we will demonstrate a quick method for manually installing PHP 8.1. Use [this link](https://windows.php.net/downloads/releases/) to download the NTS PHP 8.1 package. Extract all files from downloaded `.zip` to the previously created folder e.g `C:\PHP8.1\`. After extracting the files, you will need to choose either `php.ini-development` or `php.ini-production` and rename it to `php.ini`. This file is used to specify which extensions or settings to enable in PHP. To configure PHP properly, you will need to open the php.ini file and modify the following settings: - Set `extension_dir` to the `ext` folder located in your PHP directory (e.g. `C:\PHP8.1\ext`). - Uncomment (i.e., remove the `;` character from the beginning) some useful lines in the php.ini file. You can use the search function to locate these lines easily: ``` extension=ldap extension=curl extension=ffi extension=ftp extension=fileinfo extension=gd extension=intl extension=mbstring extension=exif extension=mysqli extension=odbc extension=openssl extension=pdo_mysq extension=pdo_odbc extension=pdo_pgsql extension=pdo_sqlite extension=pgsql extension=shmop extension=soap extension=sockets extension=sodium extension=sqlite3 extension=tidy extension=xsl zend_extension=opcache opcache.enable=1 ``` ### *Setup PHP Module Mapping in IIS 10 (If Needed)* Once PHP has been successfully installed, it must be set up in IIS10. - Open the **IIS Services Manager** and from the sidebar, click the server name. - Double-click **Handler Mappings** PHP needs to be associated with the FastCGI handler in your PHP directory. **Note:** If PHP was installed using the Web Platform Installer the handler mappings should have the FastCGI associations already. Check that the associations are correct and correspond to your local server.In the list of handler mappings the name of the mapping defaults to **PHP_via_FastCGI**,this is the mapping you will need to doublecheck. Click **OK**. If the default handler mapping for PHP FastCGI isn’t listed you will need to add it now: - In the features pane in your IIS manager, double click on the Handler Mappings feature. ![Configuring IIS Handler Mappings](/images/02/handlermapping.png) Once open, click **Add Module Mapping** on the right hand side. Enter the following information with the path to the php-cgi executable local to the server. Here is our case: Variables Values Request Path *.php Module FastCgiModule Executable “C:\PHP8.1\php-cgi.exe” Name PHPviaFastCGI ![Setting fast-cgi in IIS](/images/02/fastcgi-php.png) - Click **OK**, then click **Yes** to confirm. - Using Internet Information Services (IIS) Manager click on the server you are working with and click **Restart** from the actions pane. **Note:** Make sure that you added FastCgiModule while configuring your IIS web server. ### *Test PHP for IIS* To test PHP, we are going to create a php info file within the web root directory. Typically, this directory is located in: ``` C:\inetpub\wwwroot ``` - In the webroot directory, create an empty PHP file. At the top of file the type the following: ``` Search for “environment” in the Windows search box and then click “Edit the system environment variables”, go to the advanced tab, and click “Environment Variables”. Under System variables select “Path” and then “Edit” and then “New”. Add `c:\php` and save. The path should be at the bottom of the list. Now we will tell Apache about PHP. Go to `c:\Apache24\conf` and open the `httpd.conf` configuration file. At the very bottom add the following: ``` # PHP 81 Module # configure the path to php.ini PHPIniDir "C:/php" # before PHP 8.0.0 the name of the module was php7_module LoadModule php_module "c:/php/php8apache2_4.dll" SetHandler application/x-httpd-php ``` and then uncomment the following modules in the LoadModule section: ``` access_compat_module deflate_module filter_module rewrite_module ``` We can test everything is working by creating a `info.php` file at `Apache24/htdocs` with the following line: ``` ``` Delete default `index.html` file, restart `httpd` and go to `localhost`. You should see the php information screen. ### Configure DreamFactory with Apache Finally, we need to get DreamFactory and Apache talking to each other. For this example, it assumed that DreamFactory has been installed to `c:/dreamfactory`. First, go back to our `httpd.conf` file for Apache, and find the line `DocumentRoot "${SRVRoot}/htdocs"`. Here we will change the DocumentRoot, the Directory, and the configuration. Replace everything from ‘DocumentRoot’ to ‘’ with the following: ```text DocumentRoot "c:/dreamfactory/public" AddOutputFilterByType DEFLATE text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript Options -Indexes +FollowSymLinks -MultiViews AllowOverride All AllowOverride None Require all granted RewriteEngine on RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^.*$ /index.php [L] Allow from all ``` Save and run `httpd -t` from the command prompt (from `c:\Apache24\bin`) and you should not get any syntax errors. Start the server with `httpd` and go to `localhost/dreamfactory/dist` and you will be greeted by the login screen. ### Setting up https on Apache We can setup https on Apache using Virtual Hosts. For this example we will have dreamfactory run over http on port 80, and over port 443 at https://. Go to your Apache `httpd.conf` file and first uncomment the module `ssl_module` in the LoadModule section. Now, we will use our previous configuration, and assign it to a virtual host over port 80. Take the previous configuration and wrap it in a ` ... ` tag and also provide a servername. It should end up looking like this: ``` Listen 80 DocumentRoot "c:/dreamfactory/public" ServerName AddOutputFilterByType DEFLATE text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript Options -Indexes +FollowSymLinks -MultiViews AllowOverride All AllowOverride None Require all granted RewriteEngine on RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^.*$ /index.php [L] Allow from all ``` Now, copy everything and paste it below, changing the virtual host to 443, and adding the SSL configurations, so it ends up looking like the below: ``` Listen 443 DocumentRoot "c:/dreamfactory/public" ServerName SSLEngine on SSLCertificateFile "" SSLCertificateKeyFile "" AddOutputFilterByType DEFLATE text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript Options -Indexes +FollowSymLinks -MultiViews AllowOverride All AllowOverride None Require all granted RewriteEngine on RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^.*$ /index.php [L] Allow from all ``` Restart the Apache server and you should now have two sites, one over localhost, and one over https://localhost #### TIP If you want to redirect anything coming in over http to https, then you can simply edit the port 80 virtual host to the following: ``` Listen 80 ServerName Redirect / https:/// ``` ## Configuring Oracle on Windows with DreamFactory On Linux, our installer can handle the process of configuring Oracle with DreamFactory for you. On Windows, the process is a little more involved, but is not too taxing. You will need to download three things: 1. The Oracle “Basic” Instant Client Package from [the Oracle Website](https://www.oracle.com/database/technologies/instant-client/winx64-64-downloads.html) (for example `instantclient-basic-windows.x64-21.3.0.0.0.zip`). 2. The Oracle “SDK” Instant Client Package from [the Oracle Website](https://www.oracle.com/database/technologies/instant-client/winx64-64-downloads.html) (for example `instantclient-sdk-windows.x64-21.3.0.0.0.zip`). 3. The PHP oci8 extension (DLL) available at [pecl.php.net](https://pecl.php.net/package/oci8). By default, DreamFactory runs on PHP 8.1 so you will want the x64 package of that (version 3.2.1). If you are running DreamFactory using IIS as your webserver you will most likely be using the non thread safe version of PHP. **Note:** If you followed our guide “Install PHP for IIS” to configure PHP 8.1, the `oci8` extension should already exist in your PHP extension directory. To activate it, just in your `php.ini` file find `extension=oci8_19` and uncomment it. #### TIP On Windows you can run `php -i|findstr "Thread"` in a terminal to find out whether your PHP is the (Non) Thread Safe version. - First create a folder where you would like to keep the oracle drivers, for example `C:\oracledrivers` and extract the Oracle “Basic” Instant Client there. The files will be extracted into a subdirectoy called `instantclient_`. For example ``` C:\oracledrivers\instantclient21_3 ``` - Next, we will extract our “SDK” Instant Client *to the same folder* i.e. in this example `C:\oracledrivers`. We want the SDK package to extract into the same subdirectory that was created in the step above, not a seperate one. As a result your drivers folder would end up looking like this: ![Installing Oracle Drivers on Windows](/images/02/oracle-windows-directory.png) and our subdirectory (`instantclient_21_3` in this case) like this: ![Diagram of subtree for Oracle Drivers on Windows](/images/02/oracle-windows-subdirectory.png) You will note that there is now a `sdk` folder inside. Next, we need to add the full path of the Instant Client to the environment variables `OCI_LIB64` and `PATH`. In the Windows Control Panel go to “System and Security” -> “System” -> “Advanced System Settings”, click on Environment Variables and then: 1. Under System Variables, create `OCI_LIB64` if it does not already exist. Set the value of `OCI_LIB64` to the full path of the location of Instant Client. ![Creating OCI_LIB64 System Variable](/images/02/ocilib64-variable.png) 1. Under System Variables, edit PATH to include the same (`C:\oracledrivers\instantclient_21_3`) ![Adding Oracle to the Windows PATH](/images/02/oracle-path.png) #### Reminder! When utilizing the IIS web server, it is essential to include a new variable PATH in your FastCGI environment. For example, a new variable could be: `%PATH%;C:\oracledrivers\instantclient_21_9`. Almost there! Now, the last thing to do is to extract our PHP OCI8 extension package (It will be named along the lines of `php_oci8-3.2.1-8.1-nts-vc15-x64`) and move the `php_oci8.dll` file to the `ext` directory where PHP is located on your system (e.g `PHP\v8.1\ext`). Once that is done add `extension=php_oci8.dll` to your `php.ini` file and then restart the server (use `php -m` to make sure that the `oci8` extension is installed). Congratulations! ## Troubleshooting Oracle Connections DreamFactory uses PHP’s [OCI8](https://www.php.net/manual/en/ref.oci8.php) library to connect to and interact with databases. Therefore successful installation of the client driver and SDK is a crucial part of the process. Sometimes it is useful to attempt a connection outside of DreamFactory in order to further isolate the problem. One way to do so is by placing the following PHP script on the same server where DreamFactory is installed: ``` ``` Replace the `USERNAME`, `PASSWORD`, and `HOST/DATABASE` placeholders with your credentials, name the script `.php` or similar, and place it in the `public` directory of your DreamFactory installation. Then open a browser and navigate to `https://YOUR_DOMAIN/.php`. If the connection is successful you’ll see a corresponding message; otherwise you should see some additional details pertaining to the nature of the error. --- ## Configuring SAP SQL Anywhere SAP SQL Anywhere is the namesake commercial database solution offered by software giant SAP SE. If your organization relies upon SQL Anywhere, you’ll be pleased to know DreamFactory’s Silver and Gold editions include support for this powerful database! In this chapter we’ll walk you through the server configuration steps necessary to ensure your DreamFactory instance can interact with your SQL Anywhere database. ### Installing the PDO and PDO_DBLIB Extensions DreamFactory interacts with SQL Anywhere via the PHP Data Objects (PDO) extension. It works in conjunction with a database-specific PDO driver to interface with a wide variety of databases. Fortunately, the PDO extension and associated drivers are very easy to install. You can confirm whether PDO is already installed by running this command: ``` $ php -m ... PDO ... ``` If PDO doesn’t appear in the list of installed extensions, just search your package manager to identify the PDO package. For instance on CentOS you would search for the PDO package like so: ``` $ sudo yum search pdo ... php71-php-pdo.x86_64 php72-php-pdo.x86_64 php73-php-pdo.x86_64 ``` With the desired PHP version identified you can then install it: ``` $ yum install php81-php-pdo.x86_64 ``` Next you’ll want to install the SQL Anywhere driver. Confusingly enough, this driver is often identified as “Sybase” because SAP SQL Anywhere was known as Sybase SQL Anywhere prior to SAP’s 2010 Sybase acquisition, and the PHP community hasn’t gotten around to updating the extension’s name. On Debian/Ubuntu you can install the driver using this command: ``` $ sudo apt install php8.1-sybase ``` On CentOS this driver is identified “pdo-dblib”, because “dblib” is the name given to the library used to transfer data between the client and a database that supports a protocol known as tabular data stream (TDS - more about this in a bit). However as a convenience you can search the package manager for the term “sybase” and the desired drivers will be returned: ``` $ sudo yum search sybase ... php70-php-pdo-dblib.x86_64 php71-php-pdo-dblib.x86_64 php72-php-pdo-dblib.x86_64 php73-php-pdo-dblib.x86_64 ``` Now that you know the name you can install the desired version: ``` $ sudo yum install php81-php-pdo-dblib.x86_64 ``` Once complete, run `php -m` again and confirm both PDO and the pdo_dblib extensions are installed: ``` $ php -m ... PDO pdo_dblib ... ``` With this step complete, let’s move on to installing and configuring FreeTDS. ### Installing and Configuring FreeTDS FreeTDS is an open source implementation of a protocol known as Tabular Data Stream (TDS). This protocol is used by both SQL Anywhere and Microsoft SQL Server as a means for passing data between the databases and their respective clients. Therefore your DreamFactory server requires a TDS library which allows it to talk to these databases, and FreeTDS suits that need nicely. Open the `/etc/freetds/freetds.conf` That said, DreamFactory will not work with the SAP-produced drivers. DreamFactory’s SAP SQL Anywhere support [https://cubist.cs.washington.edu/doc/FreeTDS/userguide/x631.htm](https://cubist.cs.washington.edu/doc/FreeTDS/userguide/x631.htm) [https://www.freetds.org/userguide/choosingtdsprotocol.htm](https://www.freetds.org/userguide/choosingtdsprotocol.htm) [https://www.freetds.org/userguide/freetdsconf.htm](https://www.freetds.org/userguide/freetdsconf.htm) [https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-setup-tools?view=sql-server-2017](https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-setup-tools?view=sql-server-2017) see /etc/profile: export SQLANY17=/opt/sqlanywhere17 ([https://forums.suse.com/archive/index.php/t-2562.html](https://forums.suse.com/archive/index.php/t-2562.html)) ### Troubleshooting Your Configuration One easy way to confirm the drivers are correctly installed and that your SQL Anywhere database can be reached is by running the following command inside your Linux shell. The `SA_HOST`, `SA_PORT`, `SA_DB`, `SA_U`, and `SA_PWD` are placeholders for your SQL Anywhere host IP or domain name, port, database name, username, and password, respectively: ``` TDSDUMP="tds.log" \ php -r "new PDO('dblib:host=SA_HOST:SA_PORT;dbname=SA_DB','SA_U','SA_PWD');" ``` Invoking PHP using the `-r` option will cause the command that follows to be executed using the PHP interpreter. We prefix the `php` call with creation of the the `TDSDUMP` environment variable. When this variable is set, it will result in all traffic sent to FreeTDS to be logged to the assigned file, which in this case is `tds.log`. Once this command completes, the `tds.log` file will be found in your current directory and will contain quite a bit of information about the communication workflow associated with attempting to connect to SQL Anywhere via PHP’s PDO extension. ### Using the SAP PHP Extension A few years ago SAP released their own native SQL Anywhere PHP extension, with little background information regarding why this extension should be used in preference of PHP’s PDO-based approach. **To be clear, DreamFactory does not support the SAP PHP modules**; instead we rely upon PHP’s longstanding support for SQL Anywhere via the PDO and PDO_DBLIB extensions. That said, we recognize you might wish to use PHP to interact with a SQL Anywhere database outside of the DreamFactory-generated APIs and so because documentation on this matter is so woefully lacking we thought it might be useful to include some guidance on the matter for the benefit of all PHP users. To configure and test this module within your *custom* PHP application (not DreamFactory), follow these instructions: 1. Navigate to the following URL and download the PHP module matching your installed PHP version: [https://wiki.scn.sap.com/wiki/display/SQLANY/The+SAP+SQL+Anywhere+PHP+Module](https://wiki.scn.sap.com/wiki/display/SQLANY/The+SAP+SQL+Anywhere+PHP+Module) You can easily determine the PHP version installed on your server using the following command: ``` $ php -v PHP 7.1.22-1+0~20181001133629.6+jessie~1.gbp113f3b (cli) ... ``` 1. Move the module zip file to your server The following command will unzip the file and place its contents in a directory named `sqlanywhere-driver` found in your system’s `/tmp` directory: ``` $ unzip SQLAnywhere-php-7.1_Linux.zip -d /tmp/sqlanywhere-driver ``` If your Linux server is a fresh instance, you may need to install the unzip package first. For instance on Ubuntu/Debian you’d do so running this command: ``` $ sudo apt install unzip ``` 1. Move the module to the PHP extension directory Next you’ll move the `php7.1.0_sqlanywhere.so` module to the PHP extension directory. You can learn the extension directory’s path via this command: ``` $ php -i | grep extension_dir extension_dir => /usr/lib/php/20160303 => /usr/lib/php/2016030 ``` There are several versions of this module. You’ll find 32-bit versions in the `/tmp/sqlanywhere-driver/bin32` directory, and 64-bit versions in the `/tmp/sqlanywhere-driver/bin64` directory. Further, each of these respective directories contains a thread safe and non-thread module. If you’re using PHP’s CGI version or Apache 1.X, you’ll use the non-threaded module. If you’re using Apache 2.X or NGINX, you’ll use the threaded version, which is denoted by the `_r` filename postfix. [https://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.help.sqlanywhere.12.0.1/dbprogramming/php-s-6029035.html](https://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.help.sqlanywhere.12.0.1/dbprogramming/php-s-6029035.html) 1. Update the php.ini file and restart the web server Finally, you’ll need to update the `php.ini` file to ensure PHP recognizes the new modules. You can learn the location of this file using the following command: ``` $ php --ini ... Loaded Configuration File: /etc/php/7.1/cli/php.ini ... ``` Based on this output, the `php.ini` file is located in `/etc/php/7.1/cli/`. Keep in mind however that this `php.ini` file is *only* used in conjunction with PHP when running via the command line interface (the terminal). You’ll also want to modify the `php.ini` file used when PHP interacts with the web server. It’s location isn’t obvious when running `php --ini`, however if you navigate to the `cli` directory’s parent you’ll find the directory housing the web server-specific `php.ini` file: ``` $ cd /etc/php/7.1/ $ ls apache2 cli fpm mods-available $ ls apache2/ conf.d php.ini ``` Therefore you’ll want to update *both* `php.ini` files to ensure the SQL Anywhere modules are recognized in both environments. To do so, you’ll open up each file in a text editor and add one line: ``` extension=php-7.1.0_sqlanywhere_r.so ``` If you’re in the minority of users and require the non-threaded version, you’ll instead reference the non-threaded version: ``` extension=php-7.1.0_sqlanywhere.so ``` Keep in mind this reference must match the name of the file you copied into the PHP extensions directory! Once done, save the changes and restart your web server. Confirm PHP’s CLI environment recognizes the module by running this command: ``` $ php -m | grep sqlanywhere sqlanywhere ``` Next, confirm PHP’s web environment recognizes the module by creating a file named phpinfo.php in your web document root directory and adding the following. ## Useful System Administration Notes ### Creating a New Sudo User It’s bad practice to run system commands as the root user unless absolutely necessary. You should instead create a Sudo user that can execute commands on behalf of another user, by default the root user. To do so, you’ll first create a new user (skip this step if you instead want to add sudo capabilities to an existing user: ``` $ adduser wjgilmore Adding user `wjgilmore' ... Adding new group `wjgilmore' (1000) ... Adding new user `wjgilmore' (1000) with group `wjgilmore' ... Creating home directory `/home/wjgilmore' ... Copying files from `/etc/skel' ... Enter new UNIX password: Retype new UNIX password: passwd: password updated successfully Changing the user information for wjgilmore Enter the new value, or press ENTER for the default Full Name []: Room Number []: Work Phone []: Home Phone []: Other []: Is the information correct? [Y/n] Y ``` Next, you’ll add the user to the `sudo` group: ``` $ usermod -aG sudo wjgilmore ``` Once done, you can execute elevated commands by prefixing the command with `sudo`: ``` $ sudo ./build_system.sh ``` See these resources for more information: - [https://linuxize.com/post/how-to-create-a-sudo-user-on-debian/](https://linuxize.com/post/how-to-create-a-sudo-user-on-debian/) ## Upgrading Your DreamFactory Instance DreamFactory very much falls into the “set it and forget it” software category, often serving APIs in the background for months if not years without further human intervention. Nevertheless, we encourage users to regularly upgrade to take advantage of new features, not to mention enhanced performance and stability. Also, DreamFactory relies upon a great many dependencies such as PHP which are occasionally associated with security vulnerabilities. Accordingly, you’ll want to take care to ensure the operating system and dependecies are patched. Fortunately, upgrading DreamFactory to the latest version is a pretty straightforward process. In this section we’ll walk you through the process. ### Step #1. Back Up Your Current DreamFactory Configuration Settings A file named `.env` resides in your current DreamFactory instance’s root directory. This file contains many key system settings, including database credentials, caching preferences, and other key configurations. To backup your `.env` file, navigate to the DreamFactory root directory and copy the file to another directory: ``` $ cd /opt/dreamfactory $ cp .env ~/.env ``` Next, use SFTP or another available file transfer mechanism to move the `.env` copy to another location outside of the server. Please be sure to take this additional precaution to avoid losing any unforeseen issues which may result in file loss. ### Step #2. Back Up Your DreamFactory System Database Next we’ll create a backup copy of the production DreamFactory system database. Four system databases are supported, including MySQL, PostgreSQL, MS SQL Server, and SQLite. We will demonstrate backing up a MySQL database here, however rest assured similarly easy backup mechanisms exist for the other vendors. Just keep in mind you’ll want to backup *both* the data and data structures. To backup a MySQL database, you’ll use the `mysqldump` command: ``` $ mysqldump -u df_admin -p --databases dreamfactory --no-create-db > ~/dump.sql Enter password: ``` You can use the MySQL credentials found in your `.env` file to perform the backup. If your database name is not `dreamfactory` then update the value passed to `--databases` accordingly. The `--no-create-db` flag tells the mysqldump command to not generate a `create database` command in the dump file. Finally, the redirection operator `>` is used to redirect the dump output elsewhere, which in this case is a file named `dump.sql` that resides in the executing user’s home directory. Note this file doesn’t need to exist before executing the mysqldump command. Once complete, be sure to copy the `dump.sql` file to a safe place just as was done with the `.env` file. ### Step #3. Prepare a New Host Serve and Run Installer #### Tip If you do not use our automated installers, please follow our [Update to PHP 8.1](../upgrade-to-php-8.1/) guide. Earlier in this chapter we referred to the automated installers that are included with the platform [learn more here](https://github.com/dreamfactorysoftware/dreamfactory/tree/master/installers). We recommend downloading one of these installers from the [DreamFactory repository](https://github.com/dreamfactorysoftware/dreamfactory) and running them in the manner previously described. Four operating systems are currently supported, including CentOS, Debian, Fedora, and Ubuntu. Ideally the operating system will be newly installed, ensuring the server is free of baggage. At the installer’s conclusion you’ll be prompted to create the first administration account. Go ahead and create one, however we’ll soon be importing your existing administrator(s) from the production DreamFactory instance so ultimately the new account won’t hold any importance. ### Step #4. Disable MySQL’s Strict Mode Setting If your production DreamFactory instance uses MySQL for the system database, then you may need to disable something known as strict mode in the new MySQL database. This is because MySQL 5.7 changed how MySQL behaves in certain instances, such as whether `0000-00-00` can be treated as a valid date. Therefore if your production MySQL version is 5.6 or earlier, then you’ll almost certainly need to disable strict mode. Fortunately, this is easily done by navigating to your new DreamFactory instance’s root directory and opening `config/database.php` using a text editor like Nano or Vim. Scroll down to the `mysql` array and add this key/value pair: ``` 'strict' => false ``` ### Step #5. Import the System Database Backup Next we’ll import the MySQL database backup from your current production environment into the newly installed DreamFactory environment. Before doing so, we’ll first need to delete the contents (schema and data) of the *new* system database. To do so, navigate to your new DreamFactory installation’s root directory and run these commands: ``` $ php artisan migrate:fresh $ php artisan migrate:reset ``` Next, import the backup into the new database. Recall that this backup is found in the `dump.sql` file. Transfer the file to your new DreamFactory instance, and run this command: ``` $ mysql -u db_user -p dreamfactory_db < dump.sql Enter password: ``` You’ll need to substitute `db_user` and `dreamfactory_db` with the database username and password you supplied to the installer. Next, we’ll run the migrations command to ensure the system database contains all of the latest table structures and seed data: ``` $ php artisan migrate --seed ``` Finally, clear the cache: ``` $ php artisan cache:clear $ php artisan config:clear ``` Congratulations, you’ve successfully upgraded your DreamFactory instance! Navigate to the designated domain, and login using administrative credentials associated with your old instance. ## Conclusion With DreamFactory installed and configured, it’s time to build your first API! In the next chapter we’ll do exactly that, walking through the steps necessary to generate a database-based API. # 1 - Install DreamFactory on Windows Server 2022 with IIS Step-by-step guide to installing DreamFactory on Windows Server 2022 with IIS 10. Covers PHP setup, Apache configuration, SQL Server, and environment configuration. # Installing DreamFactory on Windows Server 2022 The following instructions are geared to a Windows Server 2022 installation, however the steps are going to be nearly identical for Windows Server 2019. > > This installation guide is meant for a “fresh” install of Windows Server 2022. > > > ## Windows Server Prep Before beginning the DreamFactory installation, there are some general server preparation steps that should be completed. Most of the following must be done with a Windows Administrator account. ### RDP While not essential to install DreamFactory, having RDP active on the server will make access and use much easier. To turn on RDP: 1. Open the Server Manager (typically opens automatically on login) 2. Select “local server” on the left 3. click on “Remote Desktop” and enable it 4. You may need to restart the server to gain RDP functionality ### Downloading files #### IE Enhanced Security By default, Windows Server 2022 comes with Microsoft Edge installed and downloads disabled with IE Enhanced Security. Within these instructions there will be multiple downloads of various tools and dependencies as well as the download of the DreamFactory code itself, to download these files on the Windows Server, IE Enhanced Security must be disabled. IE Enhanced Security can be disabled in the server manager under “Local Server”. #### Transfering files Alternatively, you can download files on a different machine, and transfer them to the Windows Server. One tool great for this is [WinSCP](https://winscp.net/eng/index.php) > > On Windows Server 2019, Edge may or may not be included, there are a few downloads in this guide that require a browser with Javascript functionality to download. It is recommended to either use another machine with a more modern browser, or download and install a different web browser on the Windows Server > > > ## Required Software There are a few things that must be installed and configured before downloading and installing DreamFactory. ### IIS Version 10 IIS version 10 comes pre-installed on Windows Server 2022, however it may need to be activated to function. While you are activating IIS, we will also activate other features we will need later. To Enable: 1. Open Server Manager 2. Click on option 2 “Add roles and features” 3. Click Next 4. Ensure “Role based or feature based” is selected, click Next 5. Ensure the server you’re working on is selected, click Next 6. Check Web Server(IIS) on server roles, install any admin tools if asked 7. Your Web Server Role should look like (but will not say “installed”): ![Web Server Role](/images/02/windows_install/select_server_roles.jpg) 1. Click Next and then Install, and let the install run ### Git Installing Git is very straightforward. Simply get the installer [here](https://git-scm.com/download/win) and run using the default options. ### Visual C++ 2015-2019 Direct download the installer using [this link](https://aka.ms/vs/16/release/VC_redist.x64.exe) Run the installer ### Install the URL rewrite IIS module Direct download [link](https://download.microsoft.com/download/D/8/1/D81E5DD6-1ABB-46B0-9B4B-21894E18B77F/rewrite_x86_en-US.msi) Run the downloaded installer. ## Install and configure PHP DreamFactory is a PHP application, following will walkthrough how to install and configure PHP 8.1.X to work with DreamFactory and IIS. ### Downloading To begin, download a **Non thread safe** version of PHP 8 - You can direct download a zip of NTS PHP 8.1.17 [here](https://windows.php.net/downloads/releases/) - OR see releases and select one [here](https://windows.php.net/download#php-8.1) - **remember to download a NON Thread Safe version!** ### Installation To install PHP, begin by making a directory in the `C:\` for the PHP installation. For this example, we are making a directory: `C:\PHP_8.1` Extract the contents of the PHP zip file into this directory. It will look something like: ![Windows Installation Screenshot](/images/02/windows_install/php_81_install.jpg) Next, this directory must be added to your system path. To do so: 1. Open Environment Variables by searching “environment” in the start menu 2. Click “Environment Variables…” 3. Select the “Path” variable and click “Edit” 4. Click “New” and add the `C:\PHP_8.1` directory 5. save and close From here, it is a good idea to test that everything is working. Open a command prompt and run `php -v` in the terminal window. You should see the version you installed in the output. If everything works, great! If not, here are some additional PHP installation resources: - [php.net Windows install](https://www.php.net/manual/en/install.windows.php) - [Microsoft PHP docs](https://learn.microsoft.com/en-us/iis/application-frameworks/install-and-configure-php-on-iis/install-and-configure-php) ### PHP configuration #### Building the .ini file Within the `C:\PHP_8.1` directory, there are two sample .ini files. `php.ini-development` and `php.ini-production` . Take one of these and duplicate the file. Rename it to `php.ini` > > You may need to [turn on file extensions]() to rename the file appropriately. > > > > > Typically during initial installation, we will use the `php.ini-development` file, and change to the `php.ini-production` one at a later date. This is entirely up to you. > > > Open `php.ini` and add the following to the bottom of the file: ``` extension=ldap extension=curl extension=ffi extension=ftp extension=fileinfo extension=gd extension=intl extension=mbstring extension=exif extension=mysqli extension=odbc extension=openssl extension=pdo_mysql extension=pdo_odbc extension=pdo_pgsql extension=pdo_sqlite extension=pgsql extension=shmop extension=soap extension=sockets extension=sodium extension=sqlite3 extension=tidy extension=xsl zend_extension=opcache opcache.enable=1 ``` > > If you are also [installing drivers for sql server](), you can add those extensions here as well. > > > #### handler mappings Handler mappings are necessary to tell IIS how to run PHP files. To configure the Handler Mappings: 1. Open IIS and click on the “Handler Mappings” icon. 2. Click on “add module mapping” on the right side 3. Fill in the module mapping: - Request Path: *.php - Module: FastCgiModule (will autofill, select that option) - Executable: Use the `...` icon and select: `C:\php_8.1\php-cgi.exe` - You might have to change the “file type” selection when browsing - Name: PHP_via_FastCGI 4. Open “Request Restrictions” and: - Mapping: File or Folder - Verbs: all - Access: script #### PHP Manager The PHP Manager is an IIS utility that gives greater insight and easier configuration options for a PHP installation. To download and install the PHP Manager: 1. The download can be found at [this link](https://www.iis.net/downloads/community/2018/05/php-manager-150-for-iis-10) click the “download this extension” button to download the executable. 2. run the downloaded file 3. If IIS is opened, close and reopen it, you should see a PHP manager icon in the IIS dashboard #### Final PHP configurations Once the PHP manager is installed, open it. If you see a warning about “non optimal PHP configuration” open the warning and apply all recommendations. Click on `check phpinfo()` , once the site opens, you should see a `phpinfo()` screen that displays the version of PHP and various configurations and installed extensions. > > The PHP manager can be used to install, enable, and disable extensions. Keep this utility in mind when troubleshooting PHP issues. > > > ### Installing Composer Composer is a dependency manager for PHP, download the installer by going [here](https://getcomposer.org/download/) Default options are fine for the composer install, you do **NOT** need to install development mode. > > to ensure composer is working, once complete run `composer --v` in a new command prompt. > > > # Installing DreamFactory Now that all the dependencies are installed, and IIS is working, we can install DreamFactory itself. It is recommended to reboot the server at this point to ensure everything is fully installed and mapped. ## Get DreamFactory code Open a fresh command prompt window, navigate (cd) to the `C:\inetpub\wwwroot\` directory. Run the git command: `git clone https://github.com/dreamfactorysoftware/dreamfactory` > > This will create a `dreamfactory` directory and add the repo contents to it. This directory is referred to as “the dreamfactory directory” in documentation and support. > > > Once complete, open the dreamfactory directory in a new file explorer window. > > If you need a different version of DreamFactory installed other than the lastest, now would be the time to use git to clone the correct branch/version. Versions older than DreamFactory V5 will need a different (older) version of PHP. > > > ## Move composer files If running a licensed, commercial instance, you will have received 3 composer files (composer.json, composer-dist.json and composer.lock) Move these 3 files into the dreamfactory directory and overwrite the existing files if asked. > > WinSCP is a great tool for getting these files from your local PC to the server. > > > ## composer command In command prompt, navigate into the dreamfactory directory and run: `composer install --ignore-platform-reqs --no-dev --verbose` Sometimes this command can take quite a bit to run, if it feels like it’s “hung” hit enter a couple times. If the command fails, it sometimes just needs to be ran again, you can [contact support](https://www.dreamfactory.com/support/) if you run into issues. ## DF setup commands Once the composer command finishes, from the dreamfactory directory run: `php artisan df:env` The installer will ask which type of database should hold the DreamFactory system information. Sqlite is the easiest to get going the fastest, however multiple databases are supported. Choose a database that fits your needs and your use case. When selecting a database name and user, we typically recommend “dreamfactory” and “dfadmin” respectively. However, these can be whatever you’d like. The user will need full permissions on that database. > > A note about system databases: > > > > > > The DreamFactory system database holds all of the configurations for your instance. Backups of this database are highly recommended when in production. You can also use a utility like `mysql dump` to pull down and later recreate the system database on another instance. This and the `.env` file will preserve all DreamFactory configurations. > > > > > > > > > Once the command finishes, run the setup command: `php artisan df:setup` This command will prompt you to create your first admin user. This will be the first account available to log in, and additional administrator accounts can be created later if desired. ## Add license key You will have received a license key, this key will need to be added to the `.env` file in the dreamfactory directory. At the bottom of the file add: `DF_LICENSE_KEY={YOUR LICENSE KEY}` > > without the curly braces > > > ## Testing From here DreamFactory is installed, the next section will focus on configuring IIS to point to and serve DreamFactory’s content. However, testing is a great and easy step here. From the dreamfactory directory, run: `php artisan serve` This will start a small development server, the output will tell you the IP address and port number to navigate to. Usually this is http://127.0.0.1:8000 Open your web browser to this address, and try to login with the user you created earlier. If you can see the DreamFactory UI and do **NOT** have a red banner at the top, you have done everything correctly. If not, go back and check your steps or [contact support](https://www.dreamfactory.com/support/) if you need help. # Adding DreamFactory to IIS IIS must be configured to serve the DreamFactory content. The following section will walk through a simple configuration. ## Creating the dreamfactory site Open IIS, if there is a Default Site on the left hand side, right click and stop it. Right click on the “Sites” folder on the left side and select “Add Website”. Fill out the Add Website dialogue: - site name: whatever you’d like can go here, we usually recommend “dreamfactory” - You may optionally select a different Application pool here - Physical path: `{dreamfactory_directory}/public` - Connect As/Test settings: Connect as “Specific User” it is recommended to start with the Administrator account, and complete the installation. Then later a service account with Admin rights can be used. - If you get green checks when selecting “Test Settings” you should be good to proceed. - optionally add a host name and IP configurations. ## Checking and adding HTTP verbs FastCGI for IIS by default doesn’t always have everything it needs configured correctly. Open the file: `C:\Windows\System32\inetsrv\config\applicationHost.config` Look for a “handlers AccessPolicy” section (ctrl + f “handlers”, usually the second instance), make sure this section looks similar to: ``` ``` > > This file does not always need changes, ensure that every handler is allowing every verb and that they are pointed to the correct php-cgi.exe (PHP 8.1) > > > ## Request filtering From the IIS window, open the “Request Filtering” icon. Go to the “HTTP Verbs” tab. Click the “Allow Verb” option on the right side and add the following verbs: - GET - HEAD - POST - DELETE - PUT - PATCH > > PROTIP: You can leave your mouse on the “Allow Verb” option and type each verb in and hit enter to confirm. > > > ## Double check web.config Most of the time this file doesn’t need to be touched, however now is a great time to check and make sure. Open the file: `{dreamfactory_dir}/public/web.config` This is a sample `web.config` file, yours may differ slightly, double check the `requestFiltering` and `DefaultDocument` sections. ``` ``` ## Import URL rewrite rules In the IIS window, open the “URL Rewrite” icon. TO import url rewrite rules: 1. Click the “Import Rules” option on the right side 2. Using the `...` icon, browse to `{dreamfactory_dir}/public/.htaccess` 3. Click “import” 4. If any of the imported rules have red X’s on them, select them and remove them until everything is green checks. 5. click “Apply” on the right side ## Set directory permissions Within the dreamfactory directory, there are `storage` and `public` directories. Set the permissions of these directories to “Full Control” for the IIS_USRS account type. Ensure these new permissions are applied recursively. ## Restart IIS and browse DreamFactory If everything was done correctly, from here you should be able to navigate in a web browser to `localhost` and see DreamFactory. Ensure that you can login with the account created earlier. You can of course [contact support](https://www.dreamfactory.com/support/) if you have additional questions or issues with your installation. # DreamFactory debugging configuration During the initial implementation phase of your instance, it might be useful to have debugging options on. These options are all found in the `.env` file within the dreamfactory directory. - `APP_DEBUG=true` - `APP_LOG_LEVEL=debug` When you have changed anything within the `.env` file, run the following two commands to ensure the changes take effect: - `php artisan config:clear` - `php artisan cache:clear`