FW System Installation for Windows

This tutorial will guide you through setting up FW on a new Windows system. If you are asked at any time during installation to create a user profile in gc (group control), make the username "admin" and the password "password". Note: the Command Prompt must always be launched in Administrator Mode.

Initial Setup for Personal Devices

If you are planning to develop on a shared computer on which another user has already set up their own FW Development Workspace, then you can skip these steps and move to Setup for All Devices. If you are the first user to set up on this computer, follow these steps as well.

1. Run Command Prompt as administrator by searching for it in the start menu -> right click -> "Run as Administrator"
2. (Check if curl is installed by opening Command Prompt and running curl --version. If the command "is not recognized", you must follow steps 2-5. Otherwise, you may skip them.) Install curl from its download page. Make sure to select the default Windows 64-bit option (not the cygwin version), as in the picture below.
3. In the "Downloads" folder, right click on your "curl" zip folder and select "Extract All…". Then click "Extract".
4. In the extracted folder, open the bin/ folder and copy curl.exe (note if using an older version of curl, you may need to use the src/ folder).
5. Paste curl.exe into C:/Windows/.
6. Download a file needed for curl

C:\Windows> curl -O https://curl.haxx.se/ca/cacert.pem

7. (Check if git is installed by opening "Command Prompt" and running git --version. If the command "is not recognized", you must follow step 7. Otherwise, you may skip it.) Download git for windows and install the program. Accept all the default installation options.
8. (Check if node is installed by opening "Command Prompt" and running node --version. If the command "is not recognized", you must follow step 8. Otherwise, you may skip it.) For compatibility purposes, we no longer use the most recent node version, but use version 12 because we are currently using gulp 4, which doesn’t work with the newest node. For most consistent compatibility use the latest node 12 version. You can download the proper Node 12 version with an installer with this link. Accept all the default installation options. After you have finished installing, restart your command line.

Setup for All Devices

Install NPM, Yarn, Gulp and Configure Git

9. Install yarn and gulp globally

    C:\> npm i -g yarn gulp

10. Configure your git profile (Use Bitbucket login information)

    C:\> git config --global user.name "[firstname] [lastname]"
    C:\> git config --global user.email "[email]"
    C:\> git config --global credential.helper 'store'

Download XAMPP and Configure PHP

11. Download XAMPP by clicking here. VERY IMPORTANT: Select the XAMPP version which goes with PHP 8.2, as this is the current PHP version our FW System uses

12. You need to make changes to your C:\xampp\php\php.ini file in order to make PHP work with the apps. Using the text editor of your choice make the following changes to php.ini

    • Set the line phar.readonly = On to phar.readonly = Off. Make sure the line is uncommented (remove the semi-colon at the beginning of the line)
    • Search for intl and uncomment the line extension=intl
    • Search for zip and uncomment the line extension=zip
    • Save your changes and close.

Configure Environment Variables

13. Make sure to note the directory where your php.exe file is located, and save it for later (it will most likely be C:\xampp\php).

14. Make a webroot folder in the C:\Users\[yourUsername] directory, then make two sub-folders: fw-dev (where nearly all work in the FW App system occurs) and bin (where our commands will be stored). This can be done by the following commands in command line:

C:\Users\[yourUserName]> mkdir webroot
C:\Users\[yourUserName]> cd webroot
C:\Users\[yourUserName]\webroot> mkdir fw-dev bin

15. Edit your Environment Variables to include three paths.

    • Press "Windows key + r" to open the run menu and run "control sysdm.cpl"
    • The "System Properties" menu should pop up. Under the "Advanced" tab, click the "Environment Variables…" button
    • Select the "Path" user variable and click the "Edit…" button
    • Add the following three paths to the Windows PATH variable (if they are not already added):
      • The newly created bin folder (ie C:\Users\[yourUserName]\webroot\bin)
      • The folder form step 14 (ie C:\xampp\php)
      • NPM Roaming Folder. (it will probably be: C:\Users\[yourUserName]\AppData\Roaming\npm).
      • "Then click "OK" to any windows that are open.
    • Note: You are only able to use these steps if you have admin access for your computer. If you are attempting to use override access with another user account it will not work. In this case, you will need to search "Edit Environment variables for your account" (rather than for the whole system) and edit the environment variables there.

Download and Setup FW Installer

16. Download the FW installer from here and save it in C:\Users\[yourUserName]\webroot\bin. Note: if you are intending to develop the FW Installer, and not just use it in production mode, please see this alternative setup for step 17.

17. Create a CMD file to run the installer:

C:\Users\[yourUserName]\webroot\bin> echo php "C:/Users/[yourUserName]/webroot/bin/fw.phar" %* > fw.cmd

18. Download Composer 2.5.5 for Windows by clicking here (just accept all defaults). You will need to scroll down to find the 2.5.5 version to download.

    • Double check that you downloaded the correct version of Composer. Open Command Prompt and type composer --version, and ensure that you are on Composer 2.5.5. If you are not, run the command composer self-update 2.5.5, and it will install the correct version.

Make Bitbucket Account

19. Make a bitbucket account here, and give Informatics Admin your username and/or email so that they can give you access to the Library Inforamtics Workspace.

20. Bitbucket is no longer allowing users to use their Atlassian passwords for Git authentication, which means you need to create an app password for this. Create an App Password by Clicking your picture in Bitbucket, clicking Personal Settings, then click App Passwords. When you Add a Password, use the following settings:

Note: Make sure to copy the password before you close the box because you won't see the password again. If you need it again, just make another Git Password the same way.

21. Restart Command line in Administrator Mode, and navigate to the fw-dev folder and Login into bitbucket on FW, using the Bitbucket account you just created. For more information on this command, click here

C:\Users\[yourUserName]\webroot\fw-dev> fw login bitbucket

Finish Setting up your FW Workspace

22. Run the setup command to set up the FW app system. For more information on this command, click here

    C:\Users\[yourUserName]\webroot\fw-dev> fw setup

23. Install Group Control, so that you can add permissions. For more information on install command click here.

C:\Users\[yourUserName]\webroot\fw-dev> fw install gc

Note: If you get Task 'Download' Failed, it means your bitbucket credentials did not work. Ensure you used your correct username and app password.

24. You will now be prompted to enter setup information. for the Web Root and App Url fields, simply hit the "enter" key to use the default values. Do the same for the the "Do you want to set up config values…" field. After hitting enter, you will need to find the Passwords entry with the credentials for your personal database. It should be called bennerlib_[yourOlivetUsername], if you don't have this take to an Informatics Administrator for them to make you a database. Enter the correct database credentials from the Passwords entry as prompted.

Note: If you get a Database migration failed, you did not correctly enter your database credentials, first ensure you typed your database credentials right by checking the file directly, found at webroot/fw-dev/config/local.php, or you can do it in the command line by running fw install --config in the gc folder (so C:\Users\[yourUserName]\webroot\fw-dev\apps\gc) and filling out all the properties as prompted. If it does not work the second time, check with an admin to make sure your database is setup correctly in Dreamhost, as described in this Knowledgebase Entry.

Configure Apache

25. Configure your Virtual Hosts. Using your preferred text editor, edit C:\xampp\apache\conf\extra\httpd-vhosts.conf by adding the following text:

<VirtualHost *:80>
        ServerName [yourUserName].localhost.com
        DocumentRoot C:/Users/[yourUserName]/webroot/fw-dev/public
        <Directory C:/Users/[yourUserName]/webroot/fw-dev/public>
                Options Indexes FollowSymLinks
                AllowOverride None
                Require all granted
        </Directory>
</VirtualHost>

Note: If a virtualhosts block called [yourUserName].localhost.com already exists, change ServerName to fw-[yourUserName].localhost.com. On a personal computer, if you wanted, you could name it fw.localhost.com, which is easier to type. Also Note: xampp comes with a couple vhosts already defined. Feel free to erase the contents and put your own virtual host. Just don’t mess up another user’s vhost (if on a shared computer).

26. Edit the file C:\Windows\System32\drivers\etc\hosts in Administrator Mode in your preferred text editor by adding the following line ([ServerName] is the ServerName in your httpd-vhosts.conf file in the previous step):

127.0.0.1   [ServerName]

27. Start or Restart Xampp by opening the Xampp control panel and clicking 'start" next to Apache. Then navigate to ServerName (by default [yourUserName].localhost.com) in your preferred web browser, and it should show you a page with a gc folder.

28. Click on GC and login with username "admin" ad password "password". If you do not receive a login error, then you have done everything correctly.

Installing Other Apps

You have successfully completed the FW Installation process. Make sure to follow our other guides to install apps for development or for production.