otuoma/Install DSpace 6 with Mirage 2 theme.ipynb

## Install DSpace 6 with Mirage 2 theme.ipynb
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part 1: Prerequisites"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install Java 8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ensure that you install the full development kit (JDK) and not the runtime environment (JRE) because we will need to compile code when installing dspace. Certain versions of Java prior to 8 update 20 and before 7 update 55 are known to have bugs that lead to errors when using tomcat8. Refer to the dspace documentation for more accurate description of these errors should you encounter them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo apt-get install openjdk-8-jdk -y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install maven and ant"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since we're building dspace with Mirage2, we need to install maven 3.3.9 or a higher version. Earlier versions will give build SUCCESS report even in cases where errors occur.\n",
    "\n",
    "Maven is used to compile the dspace source-code and is also responsible for downloading any depencies that the dspace code requires to run.\n",
    "\n",
    "Ant is used to copy the compiled code from the source folder into the deployment folder and where tomcat will be accessing it from.\n",
    "\n",
    "Both ant and maven can be installed together with this command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo apt-get install ant ant-optional maven -y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you use a proxy server in your institution to access the insternet, then you will need to configure maven to connect using the the proxy settings.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Open maven's settings.xml file with this command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo nano /usr/share/maven/conf/settings.xml"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then locate proxy settings and edit them accordingly. \n",
    "\n",
    "Remember configuring a proxy is only necessary if your institution uses a proxy server to access the internet. Otherwise you can skip this step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ----------------------------\n",
    "\n",
    "<proxy>\n",
    "    <id>%optional%</id>\n",
    "    <active>%true%</active>\n",
    "    <protocol>%http%</protocol>\n",
    "    <username>%proxyuser%</username>\n",
    "    <password>%proxypass%</password>\n",
    "    <host>%proxy.host.net%</host>\n",
    "    <port>%80%</port>\n",
    "    <nonProxyHosts>%local.net|some.host.com%</nonProxyHosts>\n",
    "</proxy>\n",
    "\n",
    "# ----------------------------\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Replace the text between % signs (including the % sign) with your institution's settings.\n",
    "\n",
    "To check the version of maven installed, issue the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mvn -v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ubuntu 16.04 will install maven 3.3.9 by default unless you choose to upgrade. If it shows a version lower than 3.3.9, you must upgrade it before proceeding.\n",
    "\n",
    "To check the version of ant installed, issue the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ant -v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install tomcat8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tomcat is the web server we will be using. Ubuntu 16.04 and debian 8 will install tomcat 8.0.32 which has a bug that will show up after installation. See the link here https://jira.duraspace.org/browse/DS-3142 for more information concerning this bug."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo apt-get install tomcat8 -y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Fix tomcat memory settings\n",
    "In the same /etc/default/tomcat8 file, find the setting JAVA_OPTS and adjust maximum and minimum memory settings accordingly depending on how much RAM you have. Tomcat8 requires at least 1GB memory to function normally."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo nano /etc/default/tomcat8"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "JAVA_OPTS=\"-Djava.awt.headless=true -Xmx2048m -Xms1024m -XX:MaxPermSize=1024m\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Enable port 80 on tomcat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, tomcat runs on port 8080 because Apache2 webserver uses port 80 by default. However, most of the time we don't have tomcat running alongside Apache2 on the same server. For this reason, we want to run tomcat on the default port 80 so that we can also end-up with a simpler and cleaner URL for our dspace installation.\n",
    "\n",
    "To run tomcat on port 80, we first need to enable the authbind setting in /etc/default/tomcat8 file. Open this file as shown in the previous step and look for the setting AUTHBIND and change it from no to yes as shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "AUTHBIND=yes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The authbind program is used to allow other programs, that do not ordinarily have access to lower port numbers (below 1023), to have access to those port numbers. We will use authbind to change tomcat's port number from the default 8080 to 80. \n",
    "\n",
    "If you're running tomcat on a higher port number, then you don't need to change this setting.\n",
    "\n",
    "Next, we need to define for authbind the port numbers that tomcat will use and then give tomcat-user and group permission to those port numbers. You can run the following commands in succession to achieve this. (Replace \"tomcat-user\" and \"tomcat-user-group\" with your actual values! )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo touch /etc/authbind/byport/80"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo touch /etc/authbind/byport/443"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo chmod 0755 /etc/authbind/byport/80"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo chmod 0755 /etc/authbind/byport/443"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo chown tomcat-user:tomcat-user-group /etc/authbind/byport/80"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo chown tomcat-user:tomcat-user-group /etc/authbind/byport/443"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Verify that the tomcat user and group have the ownership and permission to use these port numbers by running this command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ls -lh /etc/authbind/byport/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should see output similar to what is shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "-rwxr-xr-x 1 otuoma otuoma 0 Nov 23 09:42 443\n",
    "-rwxr-xr-x 1 otuoma otuoma 0 Nov 23 09:42 80"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then finally you need to define the actual port number we want to run tomcat on which is port 80. We do this by editing the file /etc/tomcat8/server.xml"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo nano /etc/tomcat8/server.xml"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Change the default port 8080 and 8443 to 80 and 443 respectively as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "<Connector port=\"80\" protocol=\"HTTP/1.1\"\n",
    "               connectionTimeout=\"20000\"\n",
    "               URIEncoding=\"UTF-8\"\n",
    "               redirectPort=\"443\" />\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Add tomcat user to dspace user group\n",
    "\n",
    "By default, tomcat will run as tomcat8 or tomcat7 depending on the version you installed. In this case, you need to grant the tomcat user ownership of the [dspace] installation folder. However, it is good that you don't interfere so much with tomcat configs. It is therefore better to let tomcat run as it's default user but give the dsapce-user the same rights as tomcat's and vice-versa.\n",
    "\n",
    "This gives the tomcat8 user permission to write to directories owned by the dspace user and vice versa. This will allow tomcat8 to write to the installation directory as well as allow us to run cronjobs using the dspace user account without running into permission issues"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo adduser tomcat8 dsapce-user"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo adduser dspace-user tomcat8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally restart tomcat with the command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo service tomcat8 restart"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Postgres and database setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dspace can use either a postgres or oracle database. Most people use postgres and it's what we'll be using in this guide.\n",
    "Intall postgres with the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo sudo apt-get install postgresql-9.5 postgresql-contrib-9.5 libpg-java -y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setup host-based access to the database\n",
    "Postgresql host-based access to the database is configured in a file that bears a name with resemblance to what it does: pg_hba.conf file. Open the file with the following command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo nano /etc/postgresql/9.5/main/pg_hba.conf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then paste the code below at the bottom of the file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "host    dspace       dspace      127.0.0.1/32         md5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will give access to a database user called \"dspace\" to a database called \"dspace\" that we have not yet created.\n",
    "\n",
    "Next, execute the following 3 commands in succession to change database user permissions to \"trust\" only."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo sed -i 's/ident/trust/' /etc/postgresql/9.5/main/pg_hba.conf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo sed -i 's/md5/trust/' /etc/postgresql/9.5/main/pg_hba.conf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo sed -i 's/peer/trust/' /etc/postgresql/9.5/main/pg_hba.conf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Restart postgresql database for these changes to take effect."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo service postgresql restart"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create the dspace database user"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Swicth to the postgres system user first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo su postgres"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When installing postgresql database, a default system user by the name postgres is created. In the above command, we have changed the commandline session to use this user's account.\n",
    "\n",
    "Then create the dspace user."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "createuser dspace"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create the dspace database"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "createdb dspace -E UNICODE "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will create a database called \"dspace\" with unicode encoding"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grant permissions to dspace user on dspace database"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Access the database shell and use the dspace database with the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "psql -d dspace"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then start by creating the pgcrypto extension to the dspace database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CREATE EXTENSION pgcrypto;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create the password"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ALTER ROLE dspace WITH PASSWORD 'db-password-here';"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Replace the text in quotes above to a password of your choice.\n",
    "\n",
    "Then give the dspace database user ownership of the dspace database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ALTER DATABASE dspace OWNER TO dspace;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then give all privileges to dspace database user on the dspace database with the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "GRANT ALL PRIVILEGES ON DATABASE dspace TO dspace;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we have a working database setup and after we install dspace, we will just need to configure our dspace installation to connect to this database."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part 2: Install Dspace"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview of DSpace Directories"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. The source directory\n",
    "It is the directory from which you compile dspace's source code. Dspace is often downloaded as a compressed file. After uncompressing, the eventual directory (from which you run the \"mvn package\" command) is what is refered to as the source directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. The installation directory\n",
    "This is the directory where compiled dspace is copied to i.e, the directory that the webapps directory, config directory, assetstore directory, log directory among others, are located. It is the directory that ant copies the compiled dspace code to. After dspace compiles successfully, you are supposed to edit the dspace.dir setting in local.cfg. The directory you specify here is the installation directory and the setting is what \"tells\" ant where to copy the compiled code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. The web deployment directory\n",
    "It is the \"webapps\" directory inside the installation directory. It contains other directories such as xmlui, jspui, solr, sword and oai. These are all web accessible endpoints on your dspace installation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mirage2 Prerequisites\n",
    "\n",
    "Building dspace with Mirage2 theme requires several applications to be installed so as to speed up the build process. If these applications are not installed, you can still build dspace with Mirage2 but the build process will have to install these applications and therefore slow down the process. The applications required are git, node, bower, grunt, compass and ruby.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install Git\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo apt-get install git"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NOTE: We need to install the following applications as the user that who will build dspace to avoid running into permission issues. This is the reason why we don't install them using the sudo command."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install node\n",
    "Download and install the node version manager with the command below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before proceeding, go to this link https://github.com/creationix/nvm/releases to check the current stable release and update the command below accordingly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before proceeding, open a different shell session and type the command below just to ensure that nvm installed correctly. If you used the above installation command without changing the version bit, it should output 0.33.11. You must exit the shell session you used to install and reopen a different one before proceeding."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nvm --version"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally let's install node itself with the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nvm install node"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NOTE: To install a specific node version e.g. 6.5.0, use: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nvm install 6.5.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install bower\n",
    "Bower can be installed using npm (node package manager), which came with node, as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "npm install -g bower"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There will be a warning about bower being deprecated but at the time of this writing, it was still working OK."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install grunt\n",
    "\n",
    "Grunt like bower, can also be installed using npm as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "npm install -g grunt && npm install -g grunt-cli"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install Ruby\n",
    "It is recommended to use RVM (ruby version manager) to install ruby. We can install rvm and ruby using this single command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "curl -sSL https://get.rvm.io | bash -s stable --ruby"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NOTE: If you encounter key verification errors during this step, run the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "curl -sSL https://rvm.io/mpapis.asc | gpg --import -"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If successful, close your shell session and reopen it again before proceeding."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install compass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gem install sass -v 3.3.14 && gem install compass -v 1.0.1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Download and extract DSpace"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The current release of dspace at the time of writing is dspace-6.3 which can be downloaded from https://github.com/DSpace/DSpace/releases/ with the command shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wget -c https://github.com/DSpace/DSpace/releases/download/dspace-6.3/dspace-6.3-release.tar.gz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will download and save dspace as dspace-6.3-release.tar.gz file.\n",
    "\n",
    "Next, we need to extract dsapce from the compressed file with the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tar -zxvf dspace-6.3-release.tar.gz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will end-up with a new directory with the name \"dspace-6.3-release\". Use the command below to get into this folder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cd dspace-6.3-release"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initial configuration\n",
    "\n",
    "At this point, we only need to define the installation directory. To do this, we need to create the configuration file using the initial file provided at [dspace/config/local.cfg.EXAMPLE]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cp dspace/config/local.cfg.EXAMPLE dspace/config/local.cfg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Open dspace/config/local.cfg file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nano dspace/config/local.cfg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Edit the dspace.dir setting as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dspace.dir=/opt/dspace-6.3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, the dspace-6.3-release directory is the source directory and /opt/dspace-6.3 is the installation directory"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Enable Mirage2 theme\n",
    "\n",
    "Enable Mirage2 theme opening dspace/config/xmlui.xconf and locate &lt;themes&gt; section and comment out the active Mirage theme and enable Mirage2 theme as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "<!-- <theme name=\"Atmire Mirage Theme\" regex=\".*\" path=\"Mirage/\" /> -->\n",
    "<theme name=\"Atmire Mirage 2 Theme\" regex=\".*\" path=\"Mirage2/\" />\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Build dspace with Mirage2 theme\n",
    "\n",
    "First ensure that you're in the source directory and issue the command below as it is to start building dspace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mvn package -Dmirage2.on=true -Dmirage2.deps.included=false"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If successful, the final output will look as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "[INFO] Reactor Summary:\n",
    "[INFO]\n",
    "[INFO] DSpace Parent Project .............................. SUCCESS [ 50.721 s]\n",
    "[INFO] DSpace Addon Modules ............................... SUCCESS [  0.025 s]\n",
    "[INFO] DSpace Kernel :: Additions and Local Customizations  SUCCESS [07:34 min]\n",
    "[INFO] DSpace XML-UI Mirage2 Theme :: Local Customisations  SUCCESS [03:17 min]\n",
    "[INFO] DSpace XML-UI (Manakin) :: Local Customizations .... SUCCESS [01:13 min]\n",
    "[INFO] DSpace JSP-UI :: Local Customizations .............. SUCCESS [ 14.703 s]\n",
    "[INFO] DSpace RDF :: Local Customizations ................. SUCCESS [04:41 min]\n",
    "[INFO] DSpace REST :: Local Customizations ................ SUCCESS [05:38 min]\n",
    "[INFO] DSpace SWORD :: Local Customizations ............... SUCCESS [  8.451 s]\n",
    "[INFO] DSpace SWORD v2 :: Local Customizations ............ SUCCESS [ 21.913 s]\n",
    "[INFO] DSpace SOLR :: Local Customizations ................ SUCCESS [04:05 min]\n",
    "[INFO] DSpace OAI-PMH :: Local Customizations ............. SUCCESS [ 27.313 s]\n",
    "[INFO] DSpace Assembly and Configuration .................. SUCCESS [ 51.855 s]\n",
    "[INFO] ------------------------------------------------------------------------\n",
    "[INFO] BUILD SUCCESS\n",
    "[INFO] ------------------------------------------------------------------------\n",
    "[INFO] Total time: 29:28 min\n",
    "[INFO] Finished at: 2018-11-23T19:05:12+03:00\n",
    "[INFO] Final Memory: 80M/192M\n",
    "[INFO] ------------------------------------------------------------------------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The entire build process takes a lot of time and from the results above you can see that it took about 30 minutes. This will largely depend on the speed of the network you're using.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install DSpace\n",
    "The next step is to copy the built files to the installation directory using ant. However, we must first ensure that this directory [/opt/dspace-6.3] exists and has the required permissions. Execute the following commands in succession to create the folder and grant permission to the tomcat8 user"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo mkdir /opt/dspace-6.3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo chown -R tomcat8:tomcat8 /opt/dspace-6.3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, change to the dspace/target/dspace-installer directory with the following command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cd dspace/target/dspace-installer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then finally install dsapce with ant"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ant fresh_install"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ant will copy the built directories from the source directory to the /opt/dsapce-6.3 directory, connect to the database and create dspace tables, and download and install the geolite database file. If successful, you should see text as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "code_folding": []
   },
   "outputs": [],
   "source": [
    " [get] .........................................\n",
    "    [untar] Expanding: /opt/dspace-6.3/config/GeoLite2-City.tar.gz into /opt/dspace-6.3/config\n",
    "   [delete] Deleting: /opt/dspace-6.3/config/GeoLite2-City.tar.gz\n",
    "     [echo]\n",
    "     [echo] ====================================================================\n",
    "     [echo]  The DSpace code has been installed.\n",
    "     [echo]\n",
    "     [echo]  To complete installation, you should do the following:\n",
    "     [echo]\n",
    "     [echo]  * Setup your Web servlet container (e.g. Tomcat) to look for your\n",
    "     [echo]    DSpace web applications in: /opt/dspace-6.3/webapps/\n",
    "     [echo]\n",
    "     [echo]    OR, copy any web applications from /opt/dspace-6.3/webapps/ to\n",
    "     [echo]    the appropriate place for your servlet container.\n",
    "     [echo]    (e.g. '$CATALINA_HOME/webapps' for Tomcat)\n",
    "     [echo]\n",
    "     [echo]  * Start up your servlet container (e.g. Tomcat). DSpace now will\n",
    "     [echo]    initialize the database on the first startup.\n",
    "     [echo]\n",
    "     [echo]  * Make an initial administrator account (an e-person) in DSpace:\n",
    "     [echo]\n",
    "     [echo]    /opt/dspace-6.3/bin/dspace create-administrator\n",
    "     [echo]\n",
    "     [echo]  You should then be able to access your DSpace's 'home page':\n",
    "     [echo]\n",
    "     [echo]    http://localhost:8080/xmlui\n",
    "     [echo]\n",
    "     [echo] ====================================================================\n",
    "     [echo]\n",
    "\n",
    "BUILD SUCCESSFUL\n",
    "Total time: 5 minutes 13 seconds\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Link tomcat8 to webapps directory\n",
    "This process involves creating symbolic links between tomcat8 and the webapps in the the webapps directory. These webapps include solr, jspui, sword, xmlui. Go to the directory /var/lib/tomcat7/webapps with the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cd /var/lib/tomcat8/webapps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then execute the following commands in succession:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    " sudo ln -s /opt/dspace-6.3/webapps/solr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    " sudo ln -s /opt/dspace-6.3/webapps/rest"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    " sudo ln -s /opt/dspace-6.3/webapps/oai"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    " sudo ln -s /opt/dspace-6.3/webapps/sword"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will ignore the jspui app because we're using Mirage2 which is in xmlui directory.\n",
    "\n",
    "Next we replace tomcat's ROOT webapp to dspace's xmlui webapp. Tomcat's ROOT webapp is the default webapp that comes with the tomcat installation. We need to replace it with dspace's xmlui webapp so that we dont have to append /xmlui on our dspace's URL to access dsapce repository.\n",
    "\n",
    "To achieve this, execute these two commands in succession:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo rm -rf /var/lib/tomcat8/webapps/ROOT"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo ln -s /opt/dspace-6.3/webapps/xmlui ROOT"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ls -lh"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The last command should show you some text that looks similar to this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lrwxrwxrwx 1 root root 27 Nov 23 21:39 oai -> /opt/dspace-6.3/webapps/oai\n",
    "lrwxrwxrwx 1 root root 28 Nov 23 21:39 rest -> /opt/dspace-6.3/webapps/rest\n",
    "lrwxrwxrwx 1 root root 29 Nov 23 21:41 ROOT -> /opt/dspace-6.3/webapps/xmlui\n",
    "lrwxrwxrwx 1 root root 28 Nov 23 21:27 solr -> /opt/dspace-6.3/webapps/solr\n",
    "lrwxrwxrwx 1 root root 29 Nov 23 21:39 sword -> /opt/dspace-6.3/webapps/sword"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally restart tomcat8"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sudo service tomcat8 restart"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Access your dspace URL in the browser to see the new dspace installation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Next : Customizing DSpace Mirage 2 theme."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Bash",
   "language": "bash",
   "name": "bash"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}