Many of the projects in the Software Engineering Project Course I teach (CS 4540/5540) at Bowling Green State University (BGSU) requires students to continue work on existing or incomplete projects. Many of these projects are built using the Laravel framework in PHP. This guide is intended to explain how to setup an Ubuntu 18.XX server to host these projects. This guide is heavily based on the work at HowToForge.

  1. When starting off any software installation on a Debian-based Linux distribution, one should always being by updating the system using the following commands. For any readers that are unfamiliar, the various pieces of this command are defined as follows:

    • sudo is a command that is short for "Super User Do". Using this command, if you have permissions, enables you to run commands as if you were the system super user.
    • apt is a package manager that is commonly used on Debian-based Linux Distributions. apt-get is a command commonly used to retrieve software packages for the system (hence the "get").
     sudo apt-get update 
     sudo apt-get upgrade
    
  2. After updating the system, it’s now time to install the latest versions of Apache Web Server, the PHP programming language, and the Composer utility. Many guides you will find elsewhere will give you different instructions to install Composer, but the software is currently a package contained within the software repository listed below, making it much easier to install.

     sudo add-apt-repository ppa:ondrej/php
     sudo apt-get update
     sudo apt-get install apache2 libapache2-mod-php7.2 php7.2 php7.2-xml php7.2-gd php7.2-opcache php7.2-mbstring php7.2-sqlite3 composer
    
  3. With the required software installed, it’s necessary to make sure that the PHP 7.0 module (or whatever other version of PHP that was previously installed) is removed. The quickest way to make sure you are removing the proper version is to 1) After entering sudo a2dismod php press the tab key which will autocomplete, providing a list of items to remove. The first command below removes the module from Apache while the second line adds the necessary module back into Apache.

     sudo a2dismod php7.0
     sudo a2enmod php7.2
    
  4. Once complete, change to the default hosting directory /var/www/html and clone your existing project using git. If for some reason git was not installed, it’s as close as a sudo apt-get install git. Make sure to clone using the https option unless you are comfortable setting up your SSH keys.

     cd /var/www/html 
     sudo git clone [PROJECT_REPOSITORY]
    
  5. Change into the newly created directory. Make sure you are in the root of the Laravel project (for some projects, you may have to go one level deeper). You will know you are in the proper directory when you directories like app and public. Once there, use composer to install the necessary packages.

     cd [NEW_DIRECTORY]
     sudo composer install
    
  6. Setting up the Sqlite database begins with the creation of a single file. Make sure to use sudo in front of this command as you will likely not have permissions to create the file without it.

     sudo touch database/database.sqlite
    
  7. With the file created, edit the .env file to setup proper database access. Typically this file will not exist at all, so you’ll first have to copy the .env-example file to .env as shown below.

     sudo cp .env-example .env
    
  8. Once the .env file is created, modify the database connection section so that it is properly set for sqlite. The details are shown below. Do make sure that the project directory is set correctly.

     DB_CONNECTION=sqlite
     DB_DATABASE=/var/www/html/[PROJECT_DIRECTORY]/database/database.sqlite
    
  9. With the database file and connection in place, all migrations and seeds can be run to 1) Create database structure and 2) Seed the database with initial data. More details on both can be found in the Laravel docs. In addition, make sure to generate the encryption key for the application or you will run into errors.

     sudo php artisan migrate
     sudo php artisan db:seed
     sudo php artisan key:generate
    
  10. With Laraval all set, Apache now needs configured for proper hosting. This begins by changing the group ownership and the permissions to certain directories within your project. This can be done with the following two lines:

    sudo chgrp -R www-data /var/www/html/your-project
    sudo chmod -R 775 /var/www/html/your-project/storage
    
  11. With correct ile permissions in place, you now have to create a configuration fiile to tell Apache where to find your project. This is accomplished by creating a new file in the /etc/apache2/sites-available directory. This directory contains multiple configurations for various websites that are available on your server. While nano is used to edit in this example, any editor can be used.

    cd /etc/apache2/sites-available
    sudo nano laravel.conf
    
  12. Enter the following code into your laravel.conf file. This tells Apache where your files are, the URL of your website, and a few other key items that allow Laravel to work.

    <VirtualHost *:80>
        ServerName URL_OF_VM
    
        ServerAdmin YourEmail@YourDomain.com
        DocumentRoot /var/www/html/[PROJECT_DIRECTORY]/public
    
        <Directory /var/www/html/PROJECT_DIRECTORY>
            AllowOverride All
        </Directory>
    
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
    </VirtualHost>
    
  13. Save your laravel.conf file.
  14. The final step involves removing the default website (a2dissite), adding your newly created site (a2ensite), enabling the rewrite module to use clean URLs (a2enmod), and the restarting the Apache service to pick up all changes.

    sudo a2dissite 000-default.conf
    sudo a2ensite laravel.conf
    sudo a2enmod rewrite
    sudo service apache2 restart
    
  15. Done!