(DEPRECATED) Windows & Apache Production Install Guide
This install guide runs you through installing Materia and all the required software on a brand new Windows Server 2012 machine. You may have some pieces of this already installed if you're already running a web server.
- Last Updated May 2018
- Materia version: v3.6.2
- Windows version: Windows Server 2012
- Apache version: 2.4.28
- MySQL version: 5.7.20
- PHP version: 7.0.25
Some of the default security settings on a new 2012 server make getting the software and setting up the server a chore. Here's our temporary suggestions to make the install easier.
In the Server Manager, go to the Dashboard tab. It should be the default tab.
Click Configure this local server
Click 'On' next to 'IE Enhanced Security Configuration' and turn it off - at least for administrators.
Click 'Private: On' next to 'Windows Firewall'. Click 'Turn Windows Firewall on or off'. Disable the private firewall.
Open Internet Explorer. Don't use recommended security settings.
Materia files will appear to be a single line on Windows (it's written with unix line endings), so you'll want a text editor that can display them properly.
Download Notepad++, SublimeText, Atom or other text editor you prefer to make editing the config files easier.
Materia releases will be compressed and packaged in .tgz files, for which you will need an extraction utility. 7-Zip is recommended, as it is both free and very easy to use.
Git is no longer required to download and install Materia, but the tools available in Git for Windows are still helpful for some of the other steps in the process - namely, Git Bash is a more readily usable terminal application over Command Prompt, and also enables the usage of an OpenSSL plugin for generating our own SSL certificates (more on that later).
All of the default selections in the Git for Windows installer will suffice.
Download the MySQL Installer. Make sure to get the correct version of MySQL - Materia uses MySQL 5.7.
Click Looking for previous GA versions? and select the most recent version of MySQL 5.7. You can also go straight to the 5.7 installer selection page.
Choose the larger of the two (currently mysql-installer-community-5.7.22.1.msi).
Select the No thanks option to download without signing up.
Run the installer.
Choose Custom as setup type.
In the list, choose the following items from the list on the left to install by clicking the green arrow pointing right:
MySQL Servers -> MySQL Server -> MySQL Server (currently 5.7) -> MySQL Server - X64
Applications -> MySQL Workbench -> MySQL Workbench (currently 6.3) -> MySQL Workbench - X64
Applications -> MySQL Utilities -> MySQL Utilities (currently 1.6) -> MySQL Utilities - X64
Click 'Next'.
The MySQL Installer will indicate that there are uninstalled requirements, but it will take care of these for you once you click 'Execute'.
Once the components are installed, clicking 'Next' should begin configuration of the MySQL server.
Select Standalone MySQL Server / Classic MySQL Replication and click 'Next'
Leave everything alone on the first page, and click 'Next'.
In the Accounts and Roles page, set the root user password as desired. Remember this password.
Click 'Next'.
Click 'Next' again.
Click 'Next' again.
Click 'Execute'.
Once everything is done running, click 'Finish'.
Click 'Next'.
Click 'Finish'.
Start the MySQL Workbench application.
Ignore the warning from MySQL Workbench regarding the operating system, it will work just fine.
Click the only MySQL instance available and use the root user password set earlier.
If a 'Query 1' tab is not already available, click the 'Create a new SQL tab for executing queries' (leftmost) button to create a new tab to run queries in.
Insert the following text:
CREATE DATABASE IF NOT EXISTS `materia`;
CREATE USER 'materia'
IDENTIFIED BY 'YOUR_PASSWORD_HERE';
GRANT ALL ON `materia`.* TO 'materia'@'%';
Be sure to replace 'YOUR_PASSWORD_HERE' with a password of your choosing. Remember this password! You'll need it later!
Click the leftmost 'Execute' (lightning bolt) button to run the above queries.
After the queries run, close the workbench.
Go to ApacheHaus and download the latest package including OpenSSL
Extract the 'Apache24' folder to the root of the C:/ drive (Result: C:/Apache24).
In the command prompt (not PowerShell):
cd C:/Apache24/bin
httpd -k install
httpd -k start
Verify that Apache is working by visiting localhost in your browser.
Download mod_xsendfile, click 'Clone or Download' then 'Download ZIP'.
Extract the contents of the file.
Copy mod_xsendfile-master/bin/Apache24/Win64/mod_xsendfile.so to C:/Apache24/modules/mod_xsendfile.so.
Edit C:/Apache24/conf/httpd.conf and add the following line under the last instance of LoadModule:
LoadModule xsendfile_module modules/mod_xsendfile.so
Define APACHE_LOG_DIR "/Apache24/logs"
Locate the line reading #LoadModule rewrite_module modules/mod_rewrite.so and remove the '#' at the beginning of the line.
Save those changes.
In Command Prompt:
cd C:/Apache24/bin
httpd -k restart
Go to Windows Control Panel -> System and Security -> System
Click Advanced System Settings
Click Environment Variables
Under 'System variables' find Path, then click 'Edit...'
Append ;C:\Apache24\bin to the end of the 'Variable value' field and click 'OK'.
Download the appropriate Thread Safe PHP 7.0 zip file
Extract the .zip file's contents to C:/php.
Rename to C:/php/php.ini-production to C:/php/php.ini, then open it in your editor.
Change the line containing extension_dir and to extension_dir = "C:\php\ext", note the lack of a semicolon at the front.
Change the value of session.save_path to C:\Temp
Locate and remove the semicolon at the beginning of each of the following lines:
;extension=php_fileinfo.dll;extension=php_gd2.dll;extension=php_mbstring.dll;extension=php_openssl.dll;extension=php_pdo_mysql.dll
Return to Windows Control Panel -> System and Security -> System
Click Advanced System Settings
Click Environment Variables
Under 'System variables' find Path, then click 'Edit...'
Append ;C:\php to the end of the 'Variable value' field and click 'OK'.
Edit C:/Apache24/conf/httpd.conf again.
Find the last LoadModule and add the following directly under it:
LoadModule php7_module "c:/php/php7apache2_4.dll"
AddType application/x-httpd-php .php
PHPIniDir "C:/php"
Find the area containing <IfModule dir_module>.
Change DirectoryIndex index.html to DirectoryIndex index.html index.php
Save the file.
In Command Prompt:
cd C:/Apache24/bin
httpd -k restart
Create the following index.php file in C:/Apache24/htdocs.
<?php phpinfo(); ?>
Now visit http://localhost/index.php to verify the php info page is functioning.
In Git Bash:
mkdir C:\ssl\private
mkdir C:\ssl\certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout C:\ssl\private\materia-selfsigned.key -out C:\ssl\certs\materia-selfsigned.crt
Provided the requested information at each prompt.
Edit C:/Apache24/conf/httpd.conf again.
Find a line reading '# Virtual Hosts'. Under this line, add
Include conf/extra/materia-vhosts.conf
Create and edit the file 'C:/Apache24/conf/extra/materia-vhosts.conf'.
Follow Materia Apache Virtual Host Configuration
Substitue the following values:
- replace all
materia.YOUR_DOMAIN.eduwith your domain (localhostfor now) - replace all
/var/www/materiawithC:/materia - replace all
/etc/ssl/withC:/ssl
Look up the list of [Materia releases] (https://github.com/ucfcdl/Materia/releases) and download the .tgz package containing the latest Materia release.
Once downloaded, use 7-Zip to extract this package to 'C:/materia'.
You will also need to create a couple of directories before running the installer, as it will expect them to exist:
cd C:/materia
mkdir fuel/app/logs
mkdir public/widget
mkdir public/widget/test
Run the Materia Installer
$ php oil r install
When prompted to choose an environment, type production.
When prompted to run the configuration wizard, type y.
We're using xsendfile, so type true at the next prompt.
If you'd like to be able to install widgets through the web administration panel, type true at the next prompt.
Type file at the next prompt to choose a cache driver, then press Enter to accept the default file location (or specify one if you want).
Type file at the next prompt to choose a session driver, then press Enter to accept the default file location (or specify one if you want).
When prompted to change the PDO connection string, type the following:
'mysql:host=localhost;dbname=materia'
For the next two options, make sure your Database user name and password match what you defined earlier in the MySQL step. If you'd like to use the generated password, make sure to make the appropriate changes through the MySQL Workbench.
Choose an LTI identifier in the next option. This should probably match the basic URL for your instance of Materia.
Unless you know better, use the default values for the LTI username variable.
If you want Materia to appear as a navigation option in the Canvas side bar, type 'true' at the next prompt. If not, 'false'.
Set shared secret and consumer keys in the next two steps - make sure your LTI installations match these later.
If you'd like to restrict logins for your instance of Materia to the LTI only (no users can log in through SAML or the normal Materia login interface), type 'true' at the next prompt. If you'd like to allow normal logins, type 'false'.
The next five options offer default values for various salts and encryption keys - you can use specific values if you desire, otherwise press 'Enter' to accept the defaults.
When prompted to make paths writable, type y.
When prompted to clear server cache, type y.
When prompted to run migrations, type y.
When prompted to populate user roles, type y.
When prompted to populate default semesters, type y.
NOTE: the semester generator is written for UCF, in which case you'll have to handle generating those yourself in the Semester script.
When prompted to create default users, type y. This will print out a set of default users and the generated passwords for those users - keep track of these.
Restart Apache:
cd C:/Apache24/bin
httpd -k restart
Updating the version of Materia running on your server is as simple as downloading the latest release package and replacing the Materia directory with the new package, with one important exception: the production configuration.
To prepare, in Git Bash, move into the C directory with cd C:/.
Back up the current version of Materia by moving it to a different location with mv materia materia-backup or any other desired location - again, this is just a backup.
Follow the instructions listed above to install Materia - again, get the latest .tgz package from Materia releases and extract it to C:/materia, overwriting the old files in the process. You won't need to run the install wizard again.
There are a few quick commands you'll need to run in order to copy some of the backed up material into the new files and prepare them for use:
cp -r materia-backup/fuel/app/config/production materia/fuel/app/config/
cp -r materia-backup/fuel/app/modules/lti/config/production materia/fuel/app/modules/lti/config/
cp -r materia-backup/fuel/app/logs materia/fuel/app/
cp -r materia-backup/public/widget materia/public/
cp -r materia-backup/fuel/packages/materia/media materia/fuel/packages/materia/
cd materia
php oil r admin:make_paths_writable
This will bring everything back up to working order.
Be sure to read release notes carefully to stay aware of any updates to Materia, and to see if any migrations are necessary.
If an update to Materia requires migrations, you can run those migrations easily:
php oil r migrate
