Merge pull request #1563 from phac-nml/update-installation-docs

Update: Installation Documenation

doc/administrator/web/building/index.md

@@ -17,7 +17,7 @@ Prerequisites
 
 The following software is required to build IRIDA from source:
 
-* Java 11 JDK (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
+* Java 17 JDK (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
 * Git (http://git-scm.com/)
 * Node (http://nodejs.org/)
 * Pnpm (https://pnpm.io/)

doc/administrator/web/centos/index.md

@@ -14,7 +14,7 @@ Installing prerequisites
 All required packages for the web interface are in the CentOS repositories. You can install them with the following commands:
 
     sudo yum -y install epel-release # for the apache native runtime
-    sudo yum -y install apr tomcat java-11-openjdk-headless mariadb-server mariadb-client tomcat-native
+    sudo yum -y install apr tomcat java-17-openjdk-headless mariadb-server mariadb-client tomcat-native
 
 Starting Tomcat and MariaDB on Startup
 --------------------------------------

doc/administrator/web/index.md

@@ -22,8 +22,8 @@ Prerequisites
 
 The following prerequisites are required for running the IRIDA web interfaces:
 
-* [Java](http://www.oracle.com/technetwork/java/index.html) 11 or higher.
-* A working servlet container supporting Servlet 3.1 ([Tomcat](https://tomcat.apache.org/), version 8 or higher, for example)
+* [Java](http://www.oracle.com/technetwork/java/index.html) 17 or higher.
+* A working servlet container supporting Servlet 3.1 ([Tomcat](https://tomcat.apache.org/), up to version 9, for example)
 * A working database server (the application is tested on [MySQL](https://www.mysql.com/) or [MariaDB](https://mariadb.org/)).
 * A working install of Galaxy (we recommend that you run Galaxy and the IRIDA web interface on separate machines).
 The install guide assumes that you are using [Bash](https://www.gnu.org/software/bash/manual/bashref.html)
@@ -45,10 +45,20 @@ Servlet Container Configuration
 -------------------------------
 Two environment variables needs to be set in your Servlet container for IRIDA to function correctly: `spring.profiles.active=prod` and `irida.db.profile=prod`.
 
-You can adjust these variables in Tomcat by editing (depending on your distribution) `/etc/tomcat/tomcat.conf` (CentOS) or `/etc/default/tomcat7` (Ubuntu), and finding the `JAVA_OPTS` variable and setting the variables as shown below:
+You can adjust these variables in Tomcat by editing (depending on your distribution) `/etc/tomcat/tomcat.conf` (CentOS) or creating a `setenv.sh` within `/opt/tomcat/bin` (Ubuntu). For CentOS you would find the `JAVA_OPTS` variable and for `Ubuntu` you would add the variables as shown below:
 
 ```
 JAVA_OPTS="-Dspring.profiles.active=prod -Dirida.db.profile=prod"
+JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64/
+
+```
+
+The JAVA_HOME path above will be something like `/usr/lib/jvm/java-17-openjdk-amd64/`
+
+If these variables were added to `/opt/tomcat/bin/setenv.sh`, then you will need to make `setenv.sh` executable. This can be done by running the command below
+
+```
+sudo chmod +X /opt/tomcat/bin/setenv.sh
 ```
 
 The `irida.db.profile=prod` option sets a number of recommended database settings for IRIDA such as JDBC, Hibernate, and Liquibase options.  See the [jdbc.prod.properties file](https://github.com/phac-nml/irida/blob/master/src/main/resources/ca/corefacility/bioinformatics/irida/config/jdbc.prod.properties) for what gets set.  All these options can be overridden in your `/etc/irida/irida.conf` file.
@@ -99,7 +109,7 @@ The main configuration parameters you will need to change are:
 5. **Security configuration**
  * `security.password.expiry` - The number of days a password is valid for in IRIDA.  After a password expires the user will be required to create a new one.  Passwords cannot be reused.
 6. **OAuth2 JWK security configuration** - IRIDA uses JWT (Json Web Tokens) for OAuth2 and as such requires a Java Key Store with an entry stored in PKCS12 format. The key pair entry can be in either RSA or EC (curves allowed are P-256, P-384, and P-121) format. The password for the keystore must be the same as the password for the key entry (This is default for PKCS12 format). (Note: these keys have nothing to do with SSL).
- * `oauth2.jwk.key-store=/etc/irida/jwk-key-store.jks` - The location of the Java Key Store 
+ * `oauth2.jwk.key-store=/etc/irida/jwk-key-store.jks` - The location of the Java Key Store
  * `oauth2.jwk.key-store-password=SECRET` - The Java Key Store password
 
 ### OAuth2 JWK Java Key Store generation
@@ -152,7 +162,7 @@ Once you have adjusted the configuration files to your environment, you can depl
 
 You can download the `WAR` file from: <https://github.com/phac-nml/irida/releases>
 
-Tomcat's deployment directory is typically some variation of `/var/lib/tomcat/webapps/`. Deploying the `WAR` file in Tomcat is as simple as moving the `WAR` file you downloaded into that directory.
+Tomcat's deployment directory is typically some variation of `/opt/tomcat/webapps/`. Deploying the `WAR` file in Tomcat is as simple as moving the `WAR` file you downloaded into that directory.
 
 On startup, IRIDA will:
 
@@ -182,7 +192,7 @@ Once you've logged in for the first time, you will probably want to create some
 
 Multi Web Server Configuration
 -------------------------------
-When IRIDA is deployed in a higher load environment, it may be preferable to deploy multiple IRIDA web application servers to handle all web requests, processing, and scheduled tasks.  IRIDA has the ability to run in a multi-server mode which will distribute these tasks among multiple servers.  This is achieved through the use of Spring profiles.  Deploying IRIDA in this fashion allows IRIDA administrators to maintain good performance for users of the IRIDA web application, while offloading some of the more resource-hungry processing tasks to additional servers.  Multiple profiles may be applied to individual servers to group some of the tasks onto one machine.  
+When IRIDA is deployed in a higher load environment, it may be preferable to deploy multiple IRIDA web application servers to handle all web requests, processing, and scheduled tasks.  IRIDA has the ability to run in a multi-server mode which will distribute these tasks among multiple servers.  This is achieved through the use of Spring profiles.  Deploying IRIDA in this fashion allows IRIDA administrators to maintain good performance for users of the IRIDA web application, while offloading some of the more resource-hungry processing tasks to additional servers.  Multiple profiles may be applied to individual servers to group some of the tasks onto one machine.
 
 Note: The `prod`, `dev` profiles and multi server configuration profiles below **cannot be used at the same time**.  Doing so may result in corrupt analysis data sets.
 

doc/administrator/web/ubuntu/index.md

@@ -6,25 +6,66 @@ description: "Ubuntu-specific install guide for setting up IRIDA."
 
 Ubuntu Installation Guide
 =========================
-Starting with a fresh, completely up-to-date system (Ubuntu Server 18.04).
+Starting with a fresh, completely up-to-date system (Ubuntu Server 24.04).
 
 Installing Software with `apt`
 ------------------------------
-You can install the latest OpenJDK JDK on Ubuntu. The `apt` repositories also contain an up-to-date version of Tomcat 8, so no complex configuration needs to take place for Ubuntu.
 
-    #### Install OpenJDK Java 11 
-    apt-get install openjdk-11-jdk
+    #### Install OpenJDK Java 17
+    sudo apt-get install openjdk-17-jdk
 
-    #### Install tomcat8 and mariadb-server
-    apt-get install --yes tomcat8 libtcnative-1 mariadb-server
+    #### Install mariadb-server
+    sudo apt-get install --yes mariadb-server
+
+    #### Download and Install tomcat9
+    sudo mkdir /opt/tomcat
+
+    For security reasons, it's best not to run Tomcat as the root user so create a dedicated user and group
+    sudo useradd -m -U -d /opt/tomcat -s /bin/false tomcat
+
+    Download [Tomcat 9](https://tomcat.apache.org/download-90.cgi)
+    sudo tar -xvf /PATH/TO/DOWNLOADED/apache-tomcat-9.0.98.tar.gz -C /opt/tomcat
+
+    Change ownership of Tomcat Directory
+    sudo groupadd tomcat
+    sudo usermod -a -G tomcat tomcat
+    sudo chown -R tomcat:tomcat /opt/tomcat
+
+    ##Update the ownership for the data directories that you have set in `/etc/irida/irida.conf`
+    sudo chown -R tomcat:tomcat /path/to/irida_data_directory
+
+    Configure Tomcat as a service
+    sudo touch /etc/systemd/system/tomcat.service
+    sudo nano /etc/systemd/system/tomcat.service
+
+    Add the following contents to the tomcat.service file above and then save.
+
+    ```
+    [Unit]
+    Description=Tomcat Server
+    After=network.target
+
+    [Service]
+    Type=forking
+    User=tomcat
+    Group=tomcat
+    Environment="JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64"
+    WorkingDirectory=/opt/tomcat/apache-tomcat-9.0.98
+    ExecStart=/opt/tomcat/apache-tomcat-9.0.98/bin/startup.sh
+
+    [Install]
+    WantedBy=multi-user.target
+    ```
+
+    Reload the systemd daemon
+    sudo systemctl daemon-reload
 
 Starting Tomcat and MariaDB on startup
 --------------------------------------
 
 The last step is to make sure that Tomcat starts on startup:
 
-
-    systemctl enable mysql # mysql is the service name for mariadb on Ubuntu
-    systemctl start mysql
-    systemctl enable tomcat8
-    systemctl start tomcat8
+    sudo systemctl enable mysql # mysql is the service name for mariadb on Ubuntu
+    sudo systemctl start mysql
+    sudo systemctl enable tomcat.service
+    sudo systemctl start tomcat.service

doc/developer/getting-started/index.md

@@ -27,7 +27,7 @@ Important links
 Languages and Libraries
 -----------------------
 
-IRIDA is a Java application developed using Java 11.
+IRIDA is a Java application developed using Java 17.
 
 #### Spring framework
 {:.no_toc}
@@ -96,7 +96,7 @@ An (incomplete) set of instructions for getting the IRIDA service layer and web
 * Clone IRIDA from the IRIDA [GitHub][].
 * Install the following dependencies from your chosen package manager:
   * MariaDB
-  * Java 11 JDK
+  * Java 17 JDK
   * Gradle
 * Create a test database in MariaDB with the name `irida_test` and user `test` with password `test`.
 * Create a second test database in MariaDB with the name `irida_integration_test` and user `test` with password `test` (for running local integration tests).

doc/developer/setup/index.md

@@ -13,7 +13,7 @@ General Requirements
 You're required to install a few different pieces of software on your machine before you can get started on hacking IRIDA:
 
 1. DB: A MySQL or MariaDB server,
-2. Languages: Java 11 (we have a hard requirement on Java 11), Python, Node
+2. Languages: Java 17 (we have a hard requirement on Java 17), Python, Node
 4. SCM: Git
 5. IDE: Eclipse, Netbeans, IntelliJ, vim... (whatever you want, really).
 
@@ -241,7 +241,7 @@ This will run all the integration test profiles using Gradle, and print out repo
 
 #### Memory requirements
 
-Your environment may throw java heap size errors when running tests. 
+Your environment may throw java heap size errors when running tests.
 
 You can increase the heap size by editing the `gradle.properties` file in the project directory and adding the following line: