Installing Loris (After Installing Prerequisites)

The following details steps for Ubuntu 16.04. Your mileage may vary.

Assumptions

1. You are on Ubuntu 16.04; lsb_release -a should say Ubuntu 16.04
2. You'll be ssh'ing into a remote machine. If you are not, just ignore the steps that tell you to ssh

Getting Prerequisites

1. ssh into your remote machine as a user in the sudo group (like root)
2. Run the following commands in sequence. If you get an error at any of the steps, troubleshoot them before continuing.
3. sudo apt-get update
4. If you'll be hosting the database locally, sudo apt-get install mysql-server
5. If you'll be hosting the database externally, sudo apt-get install mysql-client
6. sudo apt-get install -y git zip apache2 sudo curl wget python-software-properties software-properties-common
7. sudo add-apt-repository ppa:ondrej/php
8. sudo apt-get update
9. sudo apt-get install -y php7.0 php7.0-mysql php7.0-xml php7.0-json php7.0-mbstring
10. sudo apt-get install -y composer
11. sudo apt-get install -y libapache2-mod-php7.0
12. sudo a2enmod php7.0
13. sudo service apache2 restart

To future maintainers of this documentation,

PHP extensions list populated with:

for e in composer show --tree | grep -oP '\-\-\K(ext-[a-zA-Z0-9-][a-zA-Z0-9-]*)' | sort | uniq | sed 's/ext-//g'; do sudo dpkg -l | grep -wo php7.0-$e; done;

php7.0-json and php7.0-mbstring are just needed by the Loris code base for json_encode()/json_decode(), and for the user account module, respectively.

---

To future maintainers of this documentation,

If you need to know the exact names of the PHP extensions to install, run the following command,

sudo apt-cache pkgnames | grep php7 | sort

For example, ext-xml will have the package name php7.0-xml, which should be found on the output.

---

To figure out if you have a specific package installed,

sudo dpkg -l | grep <partial-or-whole-package-name>

So, to figure out if you have php7.0-xml, run sudo dpkg -l | grep php7.0-xml

So, to figure out if you have libapache2-mod-php<version>, run sudo dpkg -l | grep libapache2-mod (remember that partial package names work)

---

Terminology

• <unix-user> = The unix user you ssh with
• <loris-release-url> = The latest Loris release URL
• <project-name> = The name of your project
• <loris-directory> = The name of the Loris install directory
• <loris-host-name> = The host name of your Loris install (eg. www.example.com)
• <loris-url> = <loris-host-name> with a scheme; typically http:// or https:// (eg. http://www.example.com)
• <mysql-host-name> = The host name of your MySQL server (You usually append :3306 to it. Maybe localhost?)
• <mysql-database> = The database of your Loris install hosted on your MySQL server (Or, if you're not familiar with MySQL, the "schema")
• <mysql-admin-username> = The username of your MySQL admin account (Should have all privileges or all privileges for <mysql-database>)
• <mysql-admin-password> = The password of your MySQL admin account
• <mysql-user-username> = The username of your MySQL user account (Should have SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, CREATE TEMPORARY TABLES, LOCK TABLES granted on <mysql-database>.*)
• <mysql-user-password> = The password of your MySQL user account

Terminology - Glossary for credentials referenced elsewhere in this Wiki

• <unix-user> = lorisadmin <-- A literal string
• <loris-release-url> = No equivalent
• <project-name> = $projectname
• <loris-directory> = $projectname
• <loris-host-name> = $yourHostName/_$yourhost_
• <mysql-host-name> = $dbhost
• <mysql-database> = $dbname
• <mysql-admin-username> = lorisDBadmin <-- A literal string
• <mysql-admin-password> = $newpassword
• <mysql-user-username> = lorisuser <-- A literal string
• <mysql-user-password> = No equivalent

Creating a user for Loris

You may choose to run everything on root but that is not necessarily desirable...

1. ssh into your remote machine as a user in the sudo group (like root)
2. Run sudo useradd -U -m -G sudo -s /bin/bash <unix-user>
3. Run sudo passwd <unix-user>
4. Run su - <unix-user>
5. You should now be ssh'd as <unix-user>

In this example, loris-install-dude is the <unix-user>

Creating a directory for Loris

Make sure you're ssh'd as <unix-user>

1. Run cd /var/www (Or where your apache2 is serving files from)
2. Run sudo mkdir -m 775 -p <loris-directory>
3. Run sudo chown <unix-user>.<unix-user> <loris-directory>

If cd /var/www fails, saying the directory does not exist, make sure you have apache2 installed and that the directory /var/www is readable (and, later, writable) by the current unix user (which should be the case)

To check if you have apache2 installed, run apache2 -v. If you get an error, you do not have apache2 installed and should go install it with sudo apt-get install apache2

In this example, LorisInstall is the <loris-directory>

Getting the Release URL

Developers, ignore this. Move on to Instructions for developers.

If you're a non-developer that wants to use Git, ignore this. Move on to Instructions for developers.

1. Go to the Loris repository
2. Look for "releases"
3. Click it
4. Look for the "Latest release" label
5. Look for the "Source code" URL(s)
6. Right-click the .zip URL
7. Copy the URL (AKA "link address")
8. You now have the <loris-release-url>

The "releases" location:

The "Latest release" and "Source code" locations:

Downloading Loris

Developers, ignore this. Move on to Instructions for developers.

If you're a non-developer that wants to use Git, ignore this. Move on to Instructions for developers.

Make sure you're ssh'd as <unix-user>

1. Run cd /var/www (Or where your apache2 is serving files from)
2. Run cd <loris-directory>
3. Run sudo wget <loris-release-url> -O release.zip
4. Run sudo unzip release.zip
5. Run ls
6. You'll see a directory name that looks like Loris-XX.X.X, we'll call it <loris-release-directory>
7. Run sudo mv <loris-release-directory> Loris
8. Run ls
9. You should see that <loris-release-directory> has been renamed to Loris
10. Run sudo rm release.zip

Downloading and unzipping:

Renaming and cleaning up:

Instructions for developers

Non-developers may ignore this. It involves using Git.

1. Do everything here first

Running the Install Script

If the install script installs composer for you, delete it immediately. You should install composer separately using sudo apt-get install composer or an equivalent command.

Make sure you're ssh'd as <unix-user>

1. Run cd /var/www (Or where your apache2 is serving files from)
2. Run cd <loris-directory>
3. Run cd Loris/tools
4. Run sudo ./install.sh
5. Fill in your <project-name> (You get to choose what it is)
6. Determine if you want install.sh to configure apache2 for you
7. Key in <unix-user>'s password
8. Wait
9. Installation complete

If you get an error in the install step, you might be missing ext-xml. The prerequisites are listed at the top of this page and ext-xml is one of them. To resolve this, run sudo apt-get install php<version>-xml. If you're running PHP 7.0, it will be sudo apt-get install php7.0-xml. If you're running PHP 7.1, it will be sudo apt-get install php7.1-xml.

In this example, LorisInstall is also the <project-name> for consistency. Your project name shouldn't differ too much from your <loris-directory>.

Configuring Apache2

Assuming you let the install script configure apache2 for you but it didn't work out for some reason.

1. Run sudo a2enmod rewrite
2. Run sudo a2ensite <project-name>
3. Run sudo service apache2 restart

MySQL Administrator Account

1. Figure out the <mysql-host-name> (maybe localhost?)
2. Create a <mysql-database> for Loris (Optional)
3. The <mysql-admin-username> should have ALL privileges granted on <mysql-database> (Or all privileges on the entire MySQL server, like root)
4. Don't forget your <mysql-admin-password>!

MySQL User Account

1. The <mysql-user-username> should have SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, CREATE TEMPORARY TABLES, LOCK TABLES granted on <mysql-database>.*
2. Don't forget your <mysql-user-password>!

Installing the Database #1

If you are installing "Raisinbread", DO NOT PROCEED. If you don't know what "Raisinbread" is or are not installing it, please proceed.

Instructions for Raisinbread are here

1. Figure out your <loris-url>
2. Open your internet browser
3. Navigate to <loris-url>/installdb.php
4. Fill in <mysql-host-name> (maybe localhost?)
5. Fill in <mysql-admin-username>
6. Fill in <mysql-admin-password>
7. Fill in <mysql-database>
8. If you're a summer student, chances are, your database will have already been created for you. So, check the Use Existing Database checkbox.
9. If you're a summer student, chances are, you installed a sample data set. So, check the Do Not Install checkbox.
10. Submit

Installing the Database #2

1. Fill in <mysql-user-username>
2. Fill in <mysql-user-password>
3. If you're a summer student, chances are, your MySQL user will have already been created for you. So, check the Already Created checkbox.
4. Fill in <loris-admin-username>, you get to decide on whatever it is!
5. Fill in <loris-admin-password>, you get to decide on whatever it is!
6. Don't forget your <loris-admin-username> and <loris-admin-password>!
7. Submit
8. A config.xml file will have been created at <loris-directory>/Loris/project
9. The project folder is where your custom files go, all files in the folder are ignored by git

Filling in information:

Done!

Logging In to the Loris Admin Panel

1. Open your internet browser
2. Navigate to <loris-url>
3. Fill in <loris-admin-username>
4. Fill in <loris-admin-password>
5. Log in
6. Maybe add your username and password to a password manager?

Help! <loris-url> is loading a blank white page!

Help! <loris-url> is saying it cannot read/write templates_c!

Check the following

1. The 'base' path is configured correctly (this should be the case if done automatically). The path has to end with a forward slash / and should look like, /var/www/<loris-directory>/Loris/.

2. That <loris-directory>/Loris/smarty/templates_c exists; if it doesn't,

   1. cd <loris-directory>/Loris/smarty
   2. sudo mkdir templates_c
   3. sudo chmod 777 templates_c

3. That <loris-directory>/Loris/smarty/templates_c is owned by www-data (Run ls -al to check) or has 777 permissions (Not ideal but install.sh does something similar, Run sudo chmod 777 <loris-directory>/Loris/smarty/templates_c)