FW System Setup - Linux

This documentation is old, and has not been updated in a while, as we have not had a developer develop on Linux for several years. It will hopefully get you generally in the ballpark, however. It is recommended that you use Windows to develop the FW System, as much of our documentation is made for Windows.

This tutorial will guide you through setting up FW on a new PERSONAL (NOT INFORMATICS) ubuntu system. Note: 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"

Install Base Programs and Configure Bitbucket

  1. Open a terminal (ctrl + alt + t in ubuntu)

  2. Update your local package lists and install them (If any issues occur at this step, restart your PC)

~$ sudo apt-get update
~$ sudo apt-get upgrade
  1. Install vim, git, curl and sendmail (note: accept all defaults for phpmyadmin. Make password "password"
~$ sudo apt install vim git curl sendmail
  1. Install nvm
~$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.2/install.sh | bash
  1. Update bashrc (then close current terminal and open a new one)
~$ source ~/.bashrc
  1. Install npm
~$ nvm install node
  1. Install yarn, and gulp globally
~$ npm i -g yarn gulp
  1. Configure your git profile (Use Bitbucket login information)
~$ git config --global user.name "[firstname] [lastname]"
~$ git config --global user.email "[email]"
~$ git config --global credential.helper 'store'

Install and Setup LAMP Stack

  1. Install the LAMP stack (Apache, MySQL, and PHP), along with needed php extensions (intl & zip)
~$ sudo apt-get install apache2 php8.2 php8.2-mysql php8.2-zip php8.2-intl mysql-server libapache2-mod-php8.2 phpmyadmin

Note: we can't use sudo apt-get install lamp-server^ while it would be faster because we are not on the most current version of php. If we were using the most recent version of php, the command would be much simpler:

~$ sudo apt-get install lamp-server^ php-intl php-zip
  1. Edit mysql password settings to work with fw framework
~$ sudo mysql_secure_installation utility

Note: Make your password "password" when prompted and enter "y" for the rest of the options

  1. Turn phar.readonly off in php.ini. Run the following command and follow the steps:
~$ sudo vim /etc/php/8.2/php.ini

Now follow the following steps to edit this file: - Then type "/readonly" and hit enter (so you will go to the right line) - Press "i" to enter insert mode - Move the cursor arrow keys, and uncomment the line ;phar.readonly = on by removing the semicolon in front and changing it to phar.readonly = off - Press esc key and then type :wq and enter to save and exit.

Setup FW Workspace

  1. Make an FW directory (Where nearly all work in the FW App system occurs) and a bin directory (Where our commands will be stored)
~$ mkdir webroot webroot/fw-dev webroot/bin
  1. Download the composer setup file, run it, then move the composer.phar executable to the bin, renaming the file at the same time
~$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
~$ php composer-setup.php
~$ php -r "unlink('composer-setup.php');"
~$ mv composer.phar webroot/bin/composer
  1. Add the webroot/bin folder to the executable path. To do this Add the following line to end of ~/.bashrc (run sudo nano .bashrc):
export PATH=$PATH:~/webroot/bin
  1. Move the FW installer command to the bin folder, renaming it
    ~/webroot/bin$ curl -o fw https://linformatics.bitbucket.io/installer-new/fw.phar
    ~/webroot/bin$ chmod +x fw

  1. Make a Bitbucket account here and make sure you have access to the Library Informatics Workspace from a Informatics Admin.

  2. 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: Bitbucket App Password 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.

  1. Now that you have the Bitbucket username and App Password, login into bitbucket on FW:
    ~/webroot/fw-dev$ fw login bitbucket
  1. Run the setup command to setup the FW app system
    ~/webroot/fw-dev$ fw setup
  1. Install group control.
    ~/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.

  1. 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 this, 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, and you will need to double check that you didn't mistype anything for your database credentials by checking the file webroot/fw-dev/config/local.php.

Configure Apache

  1. Include PHPMyAdmin in apache, by running the following command:
~$ sudo vim /etc/apache2/apache2.conf

Follow the steps to edit this file: - Press "i" key to edit in vim - Add the line Include /etc/phpmyadmin/apache.conf at the bottom of the file. - Press "esc" then type :wq then the "enter" key to save (remember this for the following steps)

  1. Edit the ports.conf file
~$ sudo vim /etc/apache2/ports.conf

Comment out lines 7-13, which look like this (by adding a # before the line). Make sure to save and close.

# <IfModule ssl_module>
#           Listen 443
# </IfModule>

# <IfModule mod_gnutls.c>
#           Listen 443
# </IfModule>
  1. Create and edit the fw.conf file
~$ sudo vim /etc/apache2/sites-available/fw.conf

Copy all of the text over below, except in lines 4 and 5: substitute "[yourUbuntuUserName]" for your ubuntu username (can be found by typing echo $USER in a terminal)

<VirtualHost *:80>
        ServerName fw.localhost.com
        DocumentRoot /home/[yourUbuntuUserName]/webroot/fw-dev/public
        <Directory /home/[yourUbuntuUserName]/webroot/fw-dev/public>
                Options Indexes FollowSymLinks
                AllowOverride None
                Require all granted
        </Directory>
</VirtualHost>
  1. Symbolically link the fw.conf file to another folder
~$ sudo ln -s /etc/apache2/sites-available/fw.conf /etc/apache2/sites-enabled/fw.conf
  1. Identify your PC’s hostname by running the hostname command in a terminal (in the example below it is will-X556UAK):
will@will-X556UAK:~$ hostname
will-X556UAK
  1. Add 128.2.0.1 fw.localhost.com and 128.2.0.1 localhost.localdomain localhost [hostname] to /etc/hosts
~$ sudo vim /etc/hosts

The end result should look something like this:

127.0.0.1           localhost
127.0.0.1           will-X556UAK
127.0.0.1           fw.localhost.com
127.0.0.1           localhost.localdomain localhost will-X556UAK
  1. Restart apache to apply the changes to the apache config files
~$ sudo service apache2 restart

  1. Navigate to "fw.localhost.com" in a web browser. If done correctly, you should see a page with Index of / at the top with a link to a folder called "gc/".

  2. Click on "gc/" and login with the username "admin" and the password "password". If the login was successful, you know that your installation worked.

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.