-
Notifications
You must be signed in to change notification settings - Fork 48
Installation Instructions v4.2
This document provides install instructions of OE v4.2 in simple to follow steps.
OpenEyes™ Version 4.0.4 must be installed before its possible to update to later versions. This is due to the import requirement for DM+D data in 4.0, which needs to be in place before the migrations in later version can run. OpenEyes™ default implementation uses Apache2 Web Server, MariaDB and PHP. It is expected the user has some familiarity with these services.
OpenEyes™ v4.0.4 requires a minimum of 4GB of RAM to run the dmd-import script successfully.
The documentation below details how to install OpenEyes™ on an Linux Ubuntu server Version 20.04.6.
Please ensure that your Ubuntu-Server installation is in a clean 'just installed' state and that you did not include any additional services that was offered during the install, with the exception of sshd 'opensshd'.
We recommend that the non-root user you create is 'openeyes', if you do not follow this advice, please swap your chosen non-root username in the guide when suitable.
Assumptions
- The Ubuntu system is up to date and appropriate local user rights have been created and granted.
- You are logged into the system via ssh or a direct terminal as your non-root user 'openeyes' and that you are a member of the sudo group (which should be default).
Install Apache2 web server:
sudo apt update -y \
&& sudo apt install apache2 -y \
&& echo "Success"
Expected result
Success
Disable the firewall:
Please note this is a security concern and you should re-enable and configure the firewall as is appropriate to your deployment after the end of this guide.
sudo ufw disable \
&& echo "Success"
Expected result
Success
Ensure that the rewrite engine mod is enabled:
sudo a2enmod rewrite \
&& echo "Success"
Expected result
Success
Ensure that the headers mod is enabled:
sudo a2enmod headers \
&& echo "Success"
Expected result
Success
Restart Apache2 Service:
sudo systemctl restart apache2 \
&& echo "Success"
Expected result
Success
=============
OpenEyes Version 4.0.4 requires PHP 7.4 and several associated dependencies to be installed.
sudo apt-get update -y \
&& sudo apt -y install software-properties-common \
&& sudo add-apt-repository "ppa:ondrej/php" -y \
&& sudo apt update -y \
&& sudo apt install -y php7.4 \
&& php -v
Expected result (Approximate)
PHP 7.4.33 (cli) (built: Sep 2 2023 08:03:15) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
with Zend OPcache v7.4.33, Copyright (c), by Zend Technologies
Install PHP / OpenEyes Dependencies
Dependencies(PHP): Unit, MultiByte, DOM, XML Writer(for composer), GD, Spreadsheet, MySQL
sudo apt install -y \
php7.4-curl \
php7.4-mysql \
php-xml \
php7.4-xml \
php7.4-gd \
php7.4-mbstring \
php7.4-zip \
php7.4-gd \
phpunit \
&& echo "Success"
Expected result
Success
Install Node JS
sudo apt install nodejs unzip \
&& sudo service apache2 restart \
&& echo "Success"
Expected result
Success
(optional) Install MariaDb Client Core:
sudo apt update \
&& sudo apt install -y mariadb-client-core-10.* \
&& sudo apt install mariadb-server \
&& sudo mysql_secure_installation \
&& echo "Success"
Expected result
Success
=============
While MariaDb is the default database used with OpenEyes, its possible to use other SQL databases.
It is recommended for development purposes that MariaDb is installed via Docker. An example install would look like this:
sudo apt install -y docker.io \
&& sudo docker run --detach --name openeyes -e MYSQL_ROOT_PASSWORD=password -p 3306:3306 mariadb:10.4 \
&& echo "Success"
Details on how to install MariaDb can found at the following link: https://hub.docker.com/_/mariadb
MariaDb 10.4 is required for OpenEyes Version 4.0.4
Once MariaDb or an alternative has been installed, access the service and create a user and database.
Access mariaDb -A
mariadb --host <IP or host> --user root -p
Expected result
Welcome to the MariaDB monitor. Commands end with ; or \g.
...
MariaDB [(none)]>
Create a user:
CREATE User openeyes;
Update password for user 'openeyes':
SET PASSWORD FOR openeyes = PASSWORD('openeyes');
Create database:
CREATE database openeyes;
Grant ALL privileges (caution, for development only):
GRANT ALL PRIVILEGES ON *.* TO 'openeyes'@'%';
Flush privileges:
FLUSH PRIVILEGES;
Test database connection:
mysql --host=<IP or host> --user=openeyes --password=openeyes --database=openeyes --execute="SELECT now()" && echo "Success"
Download the sample DB from:
wget https://github.com/AppertaFoundation/openeyes-sample-db/raw/release/4.0.3/sql/sample_db.zip
Manually extract the zip file onto the server. The file is compressed with gzip. You can unzip it with zcat or just rename it to .gz and use gunzip to decompress the file.
Import the sample db to the openeyes database (you will be prompted for the password)
mysql --host=<IP or host> --user openeyes --password=openeyes --database openeyes < sample_db \
&& echo "Success"
Test the database connection; (you will be prompted for the password)
mysql --host=<IP or host> --user=openeyes --password=openeyes --database=openeyes --execute="SELECT username FROM user LIMIT 1"
Expected result
| username |
|---|
| admin |
=============
- Git clone OpenEyes code from github to the /var/www/ folder:
sudo git clone https://github.com/AppertaFoundation/openeyes.git /var/www/openeyes \
&& cd /var/www/openeyes \
&& sudo git checkout v4.0.4 \
&& echo "Success"
Run PHP Composer, this is essential to build OpenEyes. It must be ran from the /var/www/openeyes folder:
cd /var/www/openeyes \
&& curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php \
&& sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer \
&& echo "Success"
Make the local user the owner of the www/openeyes folder, replace "openeyes" with your local user name:
sudo chown -R openeyes:openeyes /var/www/openeyes \
&& echo "Success"
Run the following command to install PHP composer dependencies as non-root user in /openeyes/ folder:
composer update \
&& echo "Success"
Initialise the yii framework using the following commands in the www:
cd /var/www/openeyes/protected \
&& git submodule init \
&& git submodule update \
&& echo "Success"
Copy sample.common.php to common.php to enable local configuration:
cp /var/www/openeyes/protected/config/local.sample/common.sample.php /var/www/openeyes/protected/config/local/common.php
Update common.php with database credentials. Update the common.php file with the following underneath the $config = array section. Note this is using the Yii v1.1.22 syntax.
OEDbConnection is a unique custom db class for OpenEyes, and is required to ensure OE works correctly:
$config = array(
'components' => array(
'db' => array(
'connectionString' => 'mysql:host=localhost;dbname=openeyes',
'class' => 'OEDbConnection',
'username' => 'openeyes',
'password' => 'openeyes',
'emulatePrepare' => true,
'charset' => 'utf8',
'schemaCachingDuration' => 300,
),
),
Update the .htaccess file /var/www/openeyes/.htaccess
On the first 2 lines of the file should be the following:
Options +FollowSymLinks
IndexIgnore */*
Adjust line the text to be:
Options +FollowSymLinks
IndexIgnore /
Create the following cache directories:
mkdir -p /var/www/openeyes/cache \
mkdir -p /var/www/openeyes/protected/cache \
mkdir -p /var/www/openeyes/assets \
&& chmod -R 755 /var/www/openeyes/assets
Clone the Eyedraw module to /var/www/openeyes/protected/modules/
git clone https://github.com/AppertaFoundation/eyedraw.git /var/www/openeyes/protected/modules/eyedraw \
&& cd /var/www/openeyes/protected/modules/eyedraw \
&& git checkout v4.0.3 \
&& echo "Success"
Update permissions to openeyes directory structure:
sudo chmod 777 -R /var/www/openeyes \
&& echo "Success"
Update the OpenEyes specific Node JS dependencies from the OpenEyes root folder i.e. /var/www/openeyes/:
cd /var/www/openeyes/ \
&& curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash \
&& source ~/.bashrc \
&& nvm --version \
&& echo "Success"
Install nvm lts:
nvm install 16.20.2 \
&& nvm use 16.20.2 \
&& echo "Success"
Install node dependencies for OpenEyes:
npm install sortablejs \
&& echo "Success"
Run the OpenEyes v4.0.4 migrations:
cd /var/www/openeyes/protected/ \
&& sudo php yiic migrate --interactive=0 \
&& sudo php yiic migratemodules --interactive=0 \
&& echo "Success"
Install DM+D (v4.0.4 only)
Download the latest release from TRUD
Import the all of the files from the subfolder in the DM+D download, to the '/var/www/openeyes/protected/data/dmd_data' folder
cd /var/www/openeyes/protected/data/dmd_data \
&& unzip /dmd.zip
Run the migrations to set up the database scheme using the following command
sudo /usr/sbin/mysqld & \
sleep 5 && { \
sudo git config --global --add safe.directory /var/www/openeyes && \
cd /var/www/openeyes/protected/ && \
sudo php yiic migrate --interactive=0 && \
sudo php yiic migratemodules --interactive=0; \
cd /var/www/openeyes/protected/ && \
sudo scripts/dmd-import.sh --interactive=0 && \
sudo php yiic migratemodules --interactive=0 && \
echo "Success"; \
}
The DM+D import can take up to five minutes to complete.
=============
Note, this step must be completed for v4.0.4 but can be repeated for any v4 following v4.0.4 by checking out the relevant version and replacing the version number as follows:
sudo /usr/sbin/mysqld & \
sleep 5 && { \
sudo git config --global --add safe.directory /var/www/openeyes \
&& cd /var/www/openeyes/protected/ \
&& git checkout -f v4.2.0 \
&& sudo php yiic migrate --interactive=0 \
&& sudo php yiic migratemodules --interactive=0 \
&& sudo mysqladmin -uroot shutdown \
&& echo "Success"; \
}
Following this step, if there are issues connecting to your local MySQL server through socket "/tmp/mysql.sock", run the following:
sudo systemctl start mariadb \
&& sudo systemctl enable mariadb \
&& sudo systemctl start mysql \
&& sudo systemctl enable mysql \
&& echo "Success"
Create and configure the Apache vhost to load from /var/www/openeyes the vhost should be created as '/etc/apache2/sites-available/openeyes.conf'
Open this file and add the following content:
sudo unlink /etc/apache2/sites-enabled/000-default.conf \
&& sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/openeyes.conf
Update openeyes.conf with the following:
sudo nano /etc/apache2/sites-available/openeyes.conf
Add the following content:
<VirtualHost *:80>
ServerName localhost
DocumentRoot /var/www/openeyes
<Directory /var/www/openeyes>
Options FollowSymLinks
AllowOverride All
Order allow,deny
Allow from all
</Directory>
ErrorLog /var/log/apache2/openeyes-error.log
LogLevel warn
CustomLog /var/log/apache2/openeyes-access.log combined
</VirtualHost>
Give www-data (apache2 default user) access rights to the /var/www/openeyes folder:
sudo chown -R www-data:www-data /var/www/openeyes \
&& echo "Success"
Set openeyes as the new site for Apache2 and restart the Apache2
sudo systemctl reload apache2 \
&& sudo systemctl start mariadb \
&& sudo systemctl enable mariadb \
&& echo "Success"
You should now be able to see the OpenEyes™ login screen from the http://hostname/ where hostname is the DNS name or IP address of your server/vm. Assuming you have used the sample database, the default user account is 'admin' with password 'admin'.