This post guides you on how to configure apache2 to run as a reverse proxy in front of tomcat. The reason I personally use apache2 instead of directly exposing tomcat is because it becomes easy to install SSL certicates and automate their renewal. There could be other reasons, managing SSL certificates on tomcat is not as straight forward as itis on apache2 or other web servers such as nginx.
This guide assumes that you have installed DSpace and that it is running on port 8080 which is the default port number for a tomcat installation.
Begin with installing apache2 on your Ubuntu 18.04 as shown below
sudo apt install apache2 -y
Now when you access http://localhost on your server, you should see the default apache2 web page.
Enable mod_proxy
Issue the following command to enable mod_proxy in apache2
sudo a2enmod proxy_http
This will enable both mod proxy and mod proxy_http at once
Configure apache2 virtual hosts
Open the file /etc/apache2/sites-enabled/000-default.conf as shown below
The instructions here will show you how to install DSpace 7 on Ubuntu 18.04. It is important to note that DSpace 7 has not yet been released at the time of writing this guide. One of the main changes in DSpace 7 is that it has been split into a front-end and a back-end. The front-end is the user interface and the back-end is mostly used to serve the REST-APIs and is not user friendly. To have a fully functional dspace 7, you need to install both, preferably on the same system.
These instructions assume that you have already installed Ubuntu and is connected to the internet. The instructions also assume that you have very little understanding of the Linux commandline and advanced users will therefore find some instructions trivial.
In summary the installation shall include the following steps
Before starting, ensure that you are logged-in as a non-root user with sudo previleges, i.e., you can use sudo command. Then proceed to update your Ubuntu system with the following two commands.
sudo apt update
The above command ensures that your apt cache is updated with the latest Ubuntu package information, while the following will upgrade all the packages that need updating.
sudo apt upgrade -y
Part One: Install Prerequisites
Install Java OpenJDK 11
The official documentation for DSpace 7 has specified that Java (Oracle JDK or OpenJDK) can be used starting from version 11 or above. However, version 11 is prefered. Older versions are not supported and versions newer than 11 may work but should not be used in production.
In this guide, we shall install OpenJDK 11. OpenJDK 11 is included by default in Ubuntu 18.04’s package repository. Therefore, to install we shall need to run the command below:
sudo apt install openjdk-11-jdk
To confirm the version installed on the system, type the following command on the terminal.
java -version
The command and output of checking the java version
Install Apache Maven and Ant
DSpace 7 requires maven 3.3.x or above and and 1.8.x or above.
Maven is used to compile the dspace source-code and is also responsible for downloading any depencies that the dspace code requires to run. Ant is used to install the compiled DSpace code. On Ubuntu 18.04, install both maven and ant with with the following single command
sudo apt-get install ant ant-optional maven -y
This will install maven 3.6.0 and ant 1.10.5. To check the versions installed, see the following commands.
mvn -v
How to check Maven version
ant -version
How to check ant version
Install PostgreSQL Database v11
DSpace 7 is developed and tested on PostgreSQL 11. PostgreSQL v11 is available by default in the Ubuntu 18.04 packages repository. To install it, we shall first add its repository signing key
Set up host based access access on PostgreSQL by editing pg_hba.conf file by opening it as shown below
sudo nano /etc/postgresql/11/main/pg_hba.conf
Add the following line to the bottom of the file then save and close.
host dspace dspace 127.0.0.1/32 md5
This will set up host based type of access on a database called dspaceby the database user called dspaceon the specified localhost (127.0.0.1) address. We shall create the dspace database user and database at a later stage.
Next, execute the following 3 commands in succession to change database user permissions to “trust” only.
sudo sed -i 's/ident/trust/' /etc/postgresql/11/main/pg_hba.conf
sudo sed -i 's/md5/trust/' /etc/postgresql/11/main/pg_hba.conf
sudo sed -i 's/peer/trust/' /etc/postgresql/11/main/pg_hba.conf
Restart PostgreSQL database for these changes to take effect.
sudo systemctl restart postgresql
We now have to create the dspace database user and the dspacedatabase itself as earlier mentioned. Swicth to the postgres system user first.
sudo su postgres
When installing postgresql database, a default system user by the name postgresis created. In the above command, we have changed the commandline session to use this user’s account. Then create the dspace database user with the following command
createuser dspace
Now create the dspacedatabase with the following commands
createdb dspace -E UNICODE
This will create a database called “dspace” with unicode encoding
Next we need to grant permissions to the database user called dspaceto the database we just created, also called dspace. Access the database shell and use the dspace database with the following single command
psql -d dspace
Then start by creating the pgcrypto extension to the dspace database
CREATE EXTENSION pgcrypto;
Create the password
ALTER ROLE dspace WITH PASSWORD 'your-db-password-here';
Replace the text in quotes above to a secret password of your choice on a production system !
Then give the dspacedatabase user ownership of the dspacedatabase as shown here.
ALTER DATABASE dspace OWNER TO dspace;
Then give all privileges to dspacedatabase user on the dspacedatabase with the command below
GRANT ALL PRIVILEGES ON DATABASE dspace TO dspace;
To view the list of databases existing on the system together with other details like database ownership, issue the following command
\l
PostgreSQL shell showing several commands and their output
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 with the configured username and password on localhost.
Exit the PostgreSQK shell by the following command
\q
Exit the postgres user session with the following command
exit
Restart PostgreSQL with the following command
sudo systemctl restart postgresql
Install Apache Solr
Apache solr is the search engine used by dspace. In DSpace 7, apache solr has been decoupled from the rest of the DSpace code and you have to install and run it separately on port 8983 or another prefered port that is free on your system.
Create a directory to download and install solr. In this guide, we shall use /opt/solr-7.7 to depict the version of solr we shall use. DSpace 7 requires Solr 7.2.1 or later.
sudo mkdir /opt/solr-7.7
Change to the directory we just created
cd /opt/solr-7.7
Change the directory owner to the dspace user
sudo chown -R dspace:dspace /opt/solr-7.7
Then download solr-7.7.3 from there with the following command
Remove redundant directory and the archive we already extracted
rm -rf solr-7.7.3 solr-7.7.3.tgz
Start solr with the following command
/opt/solr-7.7/bin/solr start &
Confirm solr is running with
/opt/solr-7.7/bin/solr status
The correct output for the command /opt/solr-7.7/bin/solr status
If you access http://server-url:8983/solr in your browser, solr admin dashboard should load. If it doesn’t, review the steps followed again
Install tomcat8 servlet
DSpace 7 can function with tomcat 8 or 9. Install tomcat 8 with the following command
sudo apt install tomcat8 -y
Edit /etc/default/tomcat8 and define JAVA_HOME
sudo nano /etc/default/tomcat8
The value JAVA_HOME basically indicates to the system where your java is installed and this will depend on how you installed java and your operating system. An example of JAVA_HOME is shown below
JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk-amd64
Locate the setting JAVA_OPTS and adjust maximum and minimum memory settings accordingly depending on how much RAM your system has. Tomcat8 requires at least 1GB memory to function normally. The following setting is good for a system with 4GB RAM
Save and close the file, then restart tomcat8 as shown below
sudo systemctl restart tomcat8
Now, when you access the ip address of your system via the browser at port 8080 i.e.,http://ip-address:8080, you should see the default tomcat page, It works ! . If not, you need to review the process.
Ensure you are in the source code directory then run the command
mvn package
The output of the command if successful, will look as the image below
Install DSpace
Apache ant is now used to copy/install the compiled dspace code into the deployment directory, test if our code can conect to the database and then create necessary tables in the database for us. To do this, run these commands
cd dspace/target/dspace-installer
ant fresh_install
If successful, you should see output similar to the following
Deploy the server web app
The dspace 7 backend comprises only one web app which in our case will be located in /opt/dspace-7/webapps/server . This needs to be deployed to tomcat’s webapps directory. Use the following commands to achieve this.
Change to tomcat8’s webapps’ directory
cd /var/lib/tomcat8/webapps
Create a symbolic link to the server webapp
sudo ln -s /opt/dspace/webapps/server server
Then restart tomcat as shown in one of the previous steps. If you access http://server-ip:8080/server, you should be able to see the backend interface as shown below
Before proceeding, open a different terminal 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.35.3. You must exit the shell session you used to install and reopen a different one before proceeding.
nvm --version
Finally let’s install node v12 LTS itself with the command below
nvm install 12.18.3
Install Yarn
You can install Yarn on Ubuntu via the Debian package repository. First configure the repository:
And then build the front-end dependencies using yarn
yarn install
A screenshot of some of the previous commands
Modify the front-end to connect to your DSpace back-end by editing the following file
nano src/environments/environment.common.ts
Look for the section on The REST API server settings and modify it accordingly, for example
rest: {
ssl: false,
host: 'localhost',
port: 8080,
// NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
nameSpace: '/server/api'
}
Move the front-end files to the /opt directory change ownership to dspace system user
sudo cp -r dspace-7-angular /opt/
sudo chown dspace:dspace -R /opt/dspace-7-angular
Change to the front-end directory
cd /opt/dspace-7-angular
Build and run the front-end application
yarn start
If you encounter the error Command failed with exit code 137 it is most likely that node consumed more memory that your system can handle. Edit the file package.json with the following command
nano package.json
Then look for --max_old_space_size and edit it to ensure that the memory allocation does not exceed that which your system can handle. For instance, if you have 4GB memory on your system, you can assign it the value 3072
The command will take some time to start. When finished, you will see output similar to the following
To stop the application, press Ctrl + C. To restart the server without having to rebuild run node dist/server from the same directory. To run the command in the background, use the command
