Skip to content

Installing Loris in Depth

Laetitia Fesselier edited this page Apr 18, 2023 · 32 revisions

DEPRECATED Please refer to this documentation directory

Last tested on Ubuntu 16.04 for LORIS 21.0.1

The following instructions must be executed in sequence. If you get an error at any of the steps, troubleshoot them before continuing.

Click here for Brief installation instructions

When you're done, don't forget to continue following the rest of the Setup Guide including imaging setup.

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

RaisinBread

If you are a LORIS team developer installing RaisinBread:

  • See also the Readme in the raisinbread/ directory in this repo (choose your branch wisely)
  • Use your MCIN login to view this beta install doc

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 -y mysql-server
  5. If you'll be hosting the database externally, sudo apt-get install -y mysql-client
  6. sudo apt-get install -y zip curl wget python-software-properties software-properties-common, this will install some utilities that will help the install process
  7. sudo apt-add-repository ppa:ondrej/php, this is a personal package archive (PPA) that will allow you to install more recent versions of PHP on Ubuntu
  8. sudo apt-get update
  9. sudo apt-get install -y apache2, this installs the web server we need (apache2)
  10. sudo apt-get install -y php7.2 php7.2-mysql php7.2-xml php7.2-json php7.2-mbstring php7.2-gd, this installs PHP and the necessary extensions for LORIS to work
  11. sudo apt-get install -y composer, this is a package manager that LORIS uses for its PHP dependencies
  12. sudo apt-get install -y libapache2-mod-php7.2, this installs a module for apache2 that allows it to use PHP
  13. sudo a2enmod php7.2, this enables the module for apache2, in case it wasn't enabled before
  14. sudo service apache2 restart, this restarts the web server, allowing changes (like modules being enabled) to take effect

Ensure you have set up your MySQL root credential before continuing further.


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.2-xml, run sudo dpkg -l | grep php7.2-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-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> = loris <-- A literal string (may be something else depending on your setup)
  • <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>, this creates a user and makes some changes to the user; like adding it to the sudo group.
  3. Run sudo passwd <unix-user>, this changes the password of the newly created user
  4. Run su - <unix-user>, su is the command for "switching users".
  5. You should now be ssh'd as <unix-user>

Getting the LORIS codebase

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

  1. Run cd /var/www (Or where your apache2 is serving files from)

If you want to get the files with Git, go here

If you want to get the files via a zip file, go here

  1. Run sudo chown -R <unix-user>.<unix-user> loris

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.

Note that the path is assumed to be var/www/loris however your own path may be var/www/<project-name>, depending on your setup.

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.

Installing composer locally has been known to cause issues 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/tools
  3. Run ./install.sh
  4. Fill in your <project-name> (You get to choose what it is)
  5. Determine if you want install.sh to configure apache2 for you
  6. Key in <unix-user>'s password
  7. Wait
  8. Installation complete
  9. Run make (for production instances) or make dev (for development sandboxes)

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 php7.2-xml.

Note that the path is assumed to be var/www/loris however your own path may be var/www/<project-name>, depending on your setup.

Configuring Apache2

After running the install script, if your apache configuration isn't working, try:

  1. Run sudo a2enmod rewrite
  2. Run sudo a2ensite loris
  3. Run sudo service apache2 restart

Note that the path is assumed to be var/www/loris however your own path may be var/www/<project-name>, depending on your setup.

MySQL Information

If you are hosting the database yourself (locally or externally), go here

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?

You now have the basic LORIS features installed and are ready to set up configurations, Behavioural instruments and Imaging support.

Troubleshooting the basic installation

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

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

Verify the following in your LORIS setup

  1. The LORIS 'base' path is configured correctly in the Configuration module / back-end Config table. This should be the case if done automatically. The path has to end with a forward slash / and should look like, /var/www/loris/. If your front end isn't loading, check this Config setting via the MySQL back-end : Troubleshooting information here

  2. That loris/smarty/templates_c exists; if it doesn't,

    1. cd loris/smarty
    2. sudo mkdir templates_c
    3. sudo chmod 777 templates_c
  3. That 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/smarty/templates_c)

Note that the path is assumed to be /var/www/loris/ however your own path may be var/www/<project-name>, depending on your setup.

Clone this wiki locally