Difference between revisions of "CLIO Installation"

Latest revision as of 17:13, 10 March 2023

This section contains CLIO documentation.

Overview

CLIO is a web-based application, which means that it needs to be installed on a web server. There is no setup process for databases, meaning that the application files can be dragged directly to the applicable web server folder and accessed without installation. Different Operating Systems have different locations for their hosted content.

Creating a Local Development Environment

CLIO is a web-based application, which means that it needs to be developed on your local machine using a Local Web Development Environment (LWDE). If you are installing CLIO on a remotely hosted web server, you can ignore this section. If you are looking to test out CLIO on your local machine, though, you should follow this guide. We also provide a convenience script for Debian-based systems that will automatically install CLIO and all required software.

Download

First, we need to download the CLIO web application package which is available on our GitLab. Click on the 'Download' button, which is beside the blue 'Clone' button. We recommend downloading the project in the .zip format because it has the best cross-platform compatibility.

Clicking on 'Download' will open a pop-up for which format to download CLIO Exhibit in.

Installation

Windows

You can right-click on the “clio-exhibit-main.zip” file and select “Extract All”. Follow the prompts, choosing to open the folder when extraction is complete.

Extract CLIO Zip on Windows

Once you have extracted the ZIP file, navigate into the "clio-exhibit-main" folder within the new Explorer window.

Exploring CLIO Zip on Windows

Next, select everything in the folder and "copy” it using the right-click context menu or CTRL-C.

Copy CLIO Contents

Now we need to navigate to the Web Server host directory. If you follow the Creating a Local Web Development Environment guide, the default location is “C:\xampp\htdocs”. If there are any files or folders (such as index.html or a dashboard folder), you can safely delete them so that the folder is empty.

Pasting CLIO Content

Once you’re in this folder, you can "paste" the contents here using the right-click context menu or CTRL-V.

CLIO Installed

MacOS

You can right-click on the “clio-exhibit-main.zip” file and select “Open”. MacOS will extract the archive into the same folder as the zip file.

After extracting the zip file, open the “clio-exhibit-main” folder. Next, select everything in the folder and "copy” it using the right-click context menu or CMD-C.

Now, we need to navigate to the Web Server host directory. Open XAMPP. We will need to go to the “Volumes” tab. This will allow us to mount file system used by the web server as an accessible drive, so we can make changes to the files that are being hosted.

Click “Mount” beside the first data volume, which should be “/opt/lampp”. This will make the volume appear in Finder so we can alter files.

The web server’s contents are stored in this new mounted volume, in the htdocs folder.

Once you're in this folder, you can "paste" the contents here using the right-click context menu or CMD-V.

Linux

We offer a convenience script that can be used with Debian and most Debian-based distributions, such as Ubuntu, Kali and Linux Mint. This script can be used to install the Apache2 http web server, PHP7.4 modules, git, the Chromium web browser and the CLIO web app.

Download the script.

Once the script is downloaded, we need to make it executable. This can be done through the Debian Graphical User Interface by right clicking on the 'clio-install.sh' script file downloaded above and selecting 'Properties'. Once there, we need to go to the Permissions tab and make sure that 'Allow executing file as a program' is enabled.

Now, we can execute the script through the Terminal (also known as the command-line, console or shell), which is used to execute commands within the Debian operating system. The Terminal can be opened by pressing Control+Alt+T on your keyboard, or finding it within the Menu.

Once the Terminal is opened, we will start by typing sudo before our command. This will execute the following command as a superuser that provides the permissions necessary to install most software. If the script was placed into your Downloads folder, you can run the command sudo ~/Downloads/clio-install.sh in the Terminal window. Alternatively, you can type sudo and drag the script file to the Terminal window, which will be translated into a full path.

Once you press enter, the script will execute and will be asked for your password. When you enter the characters for your password, there will be nothing to signify that you've typed characters. After entering your password, hit enter. The script will execute and walk you through the installation. Enter your desired option and press enter to proceed.

Accessing CLIO Exhibit

Once CLIO has been installed on your web server, you can access it through your web browser. For local web development, you can navigate to http://localhost/ or http://127.0.0.1/.

CLIO in Web Browser

Note: You may need to open the XAMPP Control Panel and start the Apache web server, like shown here.

Updating CLIO Exhibit Content

CLIO Exhibit can be updated by changing files in the web server directory. This can be on a locally hosted web server, like a kiosk, or a publicly accessible web server, like your website.

Read More: Updating CLIO Exhibit Content

Documentation
Installation	Look and Feel
Interaction Modes	Developing Activity Types
Creating an Interactive	Framework
Integrating CLIO	Contribute

@@ Line 1: / Line 1: @@
-Depending on the Operating System in use, there collections of tools that achieve the same end goal through slightly different means of installation, toolkits or access.  Many Local Web Development Environment (LWDE) are available on multiple platforms, such as Microsoft Windows, Apple MacOS and many Linux-like Operating Systems.
+{{DocumentationPage}}
-== Windows ==
+== Overview ==
-The XAMPP (Cross-Platform Apache, MariaDB, PHP, and Perl) LWDE is available for download at www.apachefriends.org.  Once downloaded, the installer application can be run by double-clicking on the icon, or right clicking on it and selecting ‘Open’.  Be aware that installing this software requires administrative rights and may need permission by an IT administrator.
+CLIO is a web-based application, which means that it needs to be installed on a web server.  There is no setup process for databases, meaning that the application files can be dragged directly to the applicable web server folder and accessed without installation.  Different Operating Systems have different locations for their hosted content.
-Depending on your computer configurations, you may receive a notification about User Account Control, which is a Microsoft Windows security feature.  This warning recommends that the software be installed somewhere other than the Program Files folder.  Acknowledge the warning by clicking “OK”.
+== Creating a Local Development Environment ==
+CLIO is a web-based application, which means that it needs to be developed on your local machine using a Local Web Development Environment (LWDE).  If you are installing CLIO on a remotely hosted web server, you can ignore this section.  If you are looking to test out CLIO on your local machine, though, you should follow this guide.  We also provide a convenience script for Debian-based systems that will automatically install CLIO and all required software.
-Click “Next >” to proceed through the installation process.
+{{See|Creating a Local Web Development Environment}}
+== Download ==
+First, we need to download the CLIO web application package which is available on our [https://gitlab.com/erismuseums/clio-exhibit GitLab].  Click on the 'Download' button, which is beside the blue 'Clone' button.  We recommend downloading the project in the .zip format because it has the best cross-platform compatibility.
+[[File:CLIO Exhibit GitLab Download Popup.png|none|thumb|800x800px|Clicking on 'Download' will open a pop-up for which format to download CLIO Exhibit in.]]
-In most cases, installing the default options will provide full access to the CLIO web application.  The only components required by CLIO are Apache and PHP, which cannot be disabled in the installer.  Click “Next >” to proceed through the installation process.
+== Installation ==
-Here, we are asked to select the location where XAMPP will be installed. As noted by the warning at the start of the installation process, the default location for installation is at the root of the C: drive, in a folder called xampp.  It is not recommended that this location be changed unless User Account Control has been completely disabled.  Click “Next >” to proceed through the installation process.
+===Windows===
+You can right-click on the “clio-exhibit-main.zip” file and select “Extract All”.  Follow the prompts, choosing to open the folder when extraction is complete.
+[[File:Extract CLIO Zip on Windows.png|none|thumb|Extract CLIO Zip on Windows]]
+Once you have extracted the ZIP file, navigate into the "clio-exhibit-main" folder within the new Explorer window.
+[[File:Exploring CLIO Zip on Windows.png|none|thumb|Exploring CLIO Zip on Windows]]
+Next, select everything in the folder and "copy” it using the right-click context menu or CTRL-C.
+[[File:Copy CLIO Contents.png|none|thumb|Copy CLIO Contents]]
+Now we need to navigate to the Web Server host directory.  If you follow the [[Creating a Local Web Development Environment]] guide, the default location is “C:\xampp\htdocs”.  If there are any files or folders (such as index.html or a dashboard folder), you can safely delete them so that the folder is empty.
+[[File:Pasting CLIO Content.png|none|thumb|Pasting CLIO Content]]
+Once you’re in this folder, you can "paste" the contents here using the right-click context menu or CTRL-V.
+[[File:CLIO Installed.png|none|thumb|CLIO Installed]]
-Choose your preferred language and click “Next >” to process through the installation process.
+===MacOS===
+You can right-click on the “clio-exhibit-main.zip” file and select “Open”.  MacOS will extract the archive into the same folder as the zip file.
-Bitnami is a tool that provides quick and easy installation of popular open-source applications used in web development.  For the purposes of this project, you can untick the option to learn more.  Click “Next >” to proceed through the installation process.
+After extracting the zip file, open the “clio-exhibit-main” folder.  Next, select everything in the folder and "copy” it using the right-click context menu or CMD-C.
-Click “Next >” one final time to begin the installation of the XAMPP Local Web Development Environment.
+Now, we need to navigate to the Web Server host directory.  Open XAMPP.  We will need to go to the “Volumes” tab.  This will allow us to mount file system used by the web server as an accessible drive, so we can make changes to the files that are being hosted.
-After the installation process, you can access your new web server by opening your browser of choice, such as Google Chrome or Mozilla Firefox, and entering the web URL:  <nowiki>http://localhost/</nowiki>
+Click “Mount” beside the first data volume, which should be “/opt/lampp”.  This will make the volume appear in Finder so we can alter files.
-== MacOS ==
-The XAMPP (Cross-Platform Apache, MariaDB, PHP, and Perl) LWDE is available for MacOS at <nowiki>https://sourceforge.net/projects/xampp/files/XAMPP%20Mac%20OS%20X/</nowiki>.    We recommend using version 7.4.21, but any version should work.  The MacOS version  of  XAMPP comes in two different flavors: the installer (which runs in the background at all times) and the virtual machine (which only runs on command).  For development purposes, the ‘vm’ version works well as it can be closed completely when not needed.
-Click on “xampp-osx-7.4.21-0-vm.dmg” to download it.  Once it is downloaded, navigate to the folder containing it.
-Double-clicking on the icon, or right clicking and selecting “Open”, will mount this volume so that it can be installed.  Once opened, MacOS will begin to verify the integrity of the file to insure that corrupted data isn’t loaded.
-Once the file is verified, Finder should automatically open the volume.
+The web server’s contents are stored in this new mounted volume, in the htdocs folder.
-From here, we only need to drag the XAMPP executable to the Application folder alias to install it.
+Once you're in this folder, you can "paste" the contents here using the right-click context menu or CMD-V.
-Once the application is copied to your Applications folder, we’ll need to navigate there to run the application.  You can also use Launchpad or Search for XAMPP, if preferred.
+===Linux===
+We offer a convenience script that can be used with Debian and most Debian-based distributions, such as Ubuntu, Kali and Linux Mint.  This script can be used to install the Apache2 http web server, PHP7.4 modules, git, the Chromium web browser and the CLIO web app.
-Opening the application for the first time will result in MacOS warning you that it was downloaded from the internet.  Click ‘Open’.
+{{Script Template|Download URL=https://cliomuseums.org/clio/install_scripts/debian/clio-install.sh}}
-Next, the XAMPP application will warn you that it needs to finish initializing its components, which will require Administrative privileges.  Be aware that installing this software requires administrative rights and may need permission by an IT administrator. Click ‘OK’.
+Once the script is downloaded, we need to make it executable.  This can be done through the Debian Graphical User Interface by right clicking on the  <code>'clio-install.sh'</code> script file downloaded above and selecting <code>'Properties'</code>.  Once there, we need to go to the Permissions tab and make sure that <code>'Allow executing file as a program'</code> is enabled.
-Enter your password and hit ‘OK’.  This will finally open the main screen of the XAMPP application for MacOS.
+[[File:Debian CLIO Install Script permissions.png|frameless|500x500px]]
-In order to access the web server on your Mac computer, we will need to start some services.  This can be done by selecting “Start” on the main screen.
+Now, we can execute the script through the Terminal (also known as the command-line, console or shell), which is used to execute commands within the Debian operating system.  The Terminal can be opened by pressing Control+Alt+T on your keyboard, or finding it within the Menu.
-After you select “Start”, the red icon will turn orange while the services initialize.  If everything starts without error, the icon will turn green and the IP address field will be populated.
+[[File:Debian Terminal Screen.png|frameless|500x500px]]
-Next, we need to go to the “Services” tab and select “Start All”.  The three red icons will turn orange while the services initialize.  If everything starts without error, the icons will turn green.
+Once the Terminal is opened, we will start by typing <code>sudo</code> before our command.  This will execute the following command as a superuser that provides the permissions necessary to install most software.  If the script was placed into your Downloads folder, you can run the command <code>sudo ~/Downloads/clio-install.sh</code> in the Terminal window.  Alternatively, you can type <code>sudo</code> and drag the script file to the Terminal window, which will be translated into a full path.
-Finally, we will need to go to the “Volumes” tab.  This will allow us to mount the files used by the web server as a remote drive so we can make changes to the files that are being hosted.
+Once you press enter, the script will execute and will be asked for your password.  When you enter the characters for your password, there will be nothing to signify that you've typed characters.  After entering your password, hit enter.  The script will execute and walk you through the installation.  Enter your desired option and press enter to proceed.
-Click “Mount” beside the first data volume, which should be “/opt/lampp”.  This will make the volume appear in Finder so we can alter files.
-The web server’s contents are stored in /lampp/htdocs/.
+[[File:CLIO Debian Install Script.png|frameless|500x500px]]
-In order to access your newly installed web server’s content, you will need to go back to the “General” tab and click “Go to Application” to open your web server’s index file in your preferred browser.
+==Accessing CLIO Exhibit==
+Once CLIO has been installed on your web server, you can access it through your web browser. For local web development, you can navigate to http://localhost/ or [http://127.0.0.1/ http://127.0.0.1/.][[File:CLIO in Web Browser.png|none|thumb|CLIO in Web Browser]]{{Note|You may need to open the XAMPP Control Panel and start the Apache web server, like [[Creating_a_Local_Web_Development_Environment|shown here]].}}
-== Linux ==
+== Updating CLIO Exhibit Content ==
-{{Stub}}
+CLIO Exhibit can be updated by changing files in the web server directory.  This can be on a locally hosted web server, like a kiosk, or a publicly accessible web server, like your website.  {{See|Updating CLIO Exhibit Content}}{{DocumentationNavigation}}