Updating Manual Install Instructions Based on Feedback from slangerx

docs/installation/manual/configuring-drupal.md

@@ -20,13 +20,13 @@ The below configuration will establish `localhost` as a trusted host pattern, bu
 
 **Before** (at around line 789):
 ```
-'driver' => 'pgsql',
+'driver' => 'mysql',
 );
 ```
 
 **After**:
 ```
-'driver' => 'pgsql',
+'driver' => 'mysql',
 );
 
 $settings['trusted_host_patterns'] = [

docs/installation/manual/installing-alpaca.md

@@ -10,7 +10,9 @@
 
 ## Installing ActiveMQ
 
-In our case, the default installation method for ActiveMQ via `apt-get` will suffice.
+Some users have been able to install ActiveMQ from the standard package repositories. Others, however, have needed to install it manually.
+
+### Option 1: System Provided Packages
 
 ```bash
 sudo apt-get -y install activemq
@@ -32,15 +34,69 @@ sudo apt-cache policy activemq
 
 Write down the version listed under `Installed: `.
 
+### Option 2: Manual Install
+
+Git the latest ActiveMQ 5.x version number from https://archive.apache.org/dist/activemq which will be put in place of `[ACTIVEMQ_VERSION_NUMBER]`.
+
+```bash
+cd /opt
+sudo wget http://archive.apache.org/dist/activemq/[ACTIVEMQ_VERSION_NUMBER]/apache-activemq-[ACTIVEMQ_VERSION_NUMBER]-bin.tar.gz
+sudo tar -xvzf apache-activemq-[ACTIVEMQ_VERSION_NUMBER]-bin.tar.gz
+sudo mv apache-activemq-[ACTIVEMQ_VERSION_NUMBER] /opt/activemq
+sudo addgroup --quiet --system activemq
+sudo adduser --quiet --system --ingroup activemq --no-create-home --disabled-password activemq
+sudo chown -R activemq:activemq /opt/activemq
+sudo rm -R apache-activemq-[ACTIVEMQ_VERSION_NUMBER]-bin.tar.gz
+```
+
+Add ActiveMQ as a service:
+`/etc/systemd/system/activemq.service | root:root/644
+```
+[Unit]
+Description=Apache ActiveMQ
+After=network.target
+
+[Service]
+Type=forking
+User=activemq
+Group=activemq
+
+ExecStart=/opt/activemq/bin/activemq start
+ExecStop=/opt/activemq/bin/activemq stop
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Update the WebConsolePort host property settings in `/opt/activemq/conf/jetty.xml` from `<property name="host" value="127.0.0.1"/>` to `<property name="host" value="0.0.0.0"/>` so that you can access the dashboard from outside the local machine.
+
+Optionally, change the dashboard user credentials in `/opt/activemq/conf/users.properties`.
+
+!!! warning "Security Warning"
+    Updating the web console port and user properties are potential security holes. It is best to restrict the host setting and create a more secure username/password combination for production.
+
+Set the service to start on machine startup and start it up:
+```bash
+sudo systemctl daemon-reload
+sudo systemctl start activemq
+sudo systemctl enable activemq
+sudo systemctl status activemq
+sudo systemctl restart activemq
+sudo apt-cache policy activemq   # note version number
+```
+
+The service should now be available at `http://localhost:8161/`
+
+
 ## Installing Alpaca
 
 Install Java 11+ if you haven't already.
 
 Make a directory for Alpaca and download the latest version of Alpaca from the [Maven repository](https://repo1.maven.org/maven2/ca/islandora/alpaca/islandora-alpaca-app). E.g.
 ```
-mkdir /opt/alpaca
+sudo mkdir /opt/alpaca
 cd /opt/alpaca
-curl -L https://repo1.maven.org/maven2/ca/islandora/alpaca/islandora-alpaca-app/2.2.0/islandora-alpaca-app-2.2.0-all.jar -o alpaca.jar
+sudo curl -L https://repo1.maven.org/maven2/ca/islandora/alpaca/islandora-alpaca-app/2.2.0/islandora-alpaca-app-2.2.0-all.jar -o alpaca.jar
 ```
 
 ### Configuration
@@ -55,7 +111,7 @@ The properties are:
 
 ```
 # Common options
-error.maxRedeliveries=4
+error.maxRedeliveries=5
 ```
 This defines how many times to retry a message before failing completely.
 
@@ -79,11 +135,6 @@ jms.connections=10
 ```
 This defines the pool of connections to the ActiveMQ instance.
 
-```
-jms.concurrent-consumers=1
-```
-This defines how many messages to process simultaneously.
-
 #### islandora-indexing-fcrepo
 
 This service manages a Drupal node into a corresponding Fedora resource.
@@ -108,20 +159,20 @@ These define the various queues to listen on for the indexing/deletion
 messages. The part after `queue:` should match your Islandora instance "Actions".
 
 ```
-fcrepo.indexer.milliner.baseUrl=http://localhost:8000/milliner
+fcrepo.indexer.milliner.baseUrl=http://localhost/milliner
 ```
 This defines the location of your Milliner microservice.
 
 ```
-fcrepo.indexer.concurrent-consumers=1
-fcrepo.indexer.max-concurrent-consumers=1
+fcrepo.indexer.concurrent-consumers=-1
+fcrepo.indexer.max-concurrent-consumers=-1
 ```
 These define the default number of concurrent consumers and maximum number of concurrent
 consumers working off your ActiveMQ instance.
 A value of `-1` means no setting is applied.
 
 ```
-fcrepo.indexer.async-consumer=true
+fcrepo.indexer.async-consumer=false
 ```
 
 This property allows the concurrent consumers to process concurrently; otherwise, the consumers will wait to the previous message has been processed before executing.
@@ -134,7 +185,7 @@ It's properties are:
 
 ```
 # Triplestore indexer options
-triplestore.indexer.enabled=false
+triplestore.indexer.enabled=true
 ```
 
 This defines whether the Triplestore indexer is enabled or not.
@@ -154,8 +205,8 @@ triplestore.baseUrl=http://localhost:8080/bigdata/namespace/kb/sparql
 This defines the location of your triplestore's SPARQL update endpoint.
 
 ```
-triplestore.indexer.concurrent-consumers=1
-triplestore.indexer.max-concurrent-consumers=1
+triplestore.indexer.concurrent-consumers=-1
+triplestore.indexer.max-concurrent-consumers=-1
 ```
 
 These define the default number of concurrent consumers and maximum number of concurrent
@@ -164,7 +215,7 @@ A value of `-1` means no setting is applied.
 
 
 ```
-triplestore.indexer.async-consumer=true
+triplestore.indexer.async-consumer=false
 ```
 
 This property allows the concurrent consumers to process concurrently; otherwise, the consumers will wait to the previous message has been processed before executing.
@@ -184,7 +235,7 @@ derivative.<item>.enabled=true
 This defines if the `item` service is enabled.
 
 ```
-derivative.<item>.in.stream=queue:islandora-item-connector.index
+derivative.<item>.in.stream=queue:islandora-item-connector-<item>
 ```
 
 This is the input queue for the derivative microservice.
@@ -197,8 +248,8 @@ derivative.<item>.service.url=http://example.org/derivative/convert
 This is the microservice URL to process the request.
 
 ```
-derivative.<item>.concurrent-consumers=1
-derivative.<item>.max-concurrent-consumers=1
+derivative.<item>.concurrent-consumers=-1
+derivative.<item>.max-concurrent-consumers=-1
 ```
 
 These define the default number of concurrent consumers and maximum number of concurrent
@@ -207,7 +258,7 @@ A value of `-1` means no setting is applied.
 
 
 ```
-derivative.<item>.async-consumer=true
+derivative.<item>.async-consumer=false
 ```
 
 This property allows the concurrent consumers to process concurrently; otherwise, the consumers will wait to the previous message has been processed before executing.
@@ -219,14 +270,14 @@ derivative.systems.installed=houdini,fits
 
 derivative.houdini.enabled=true
 derivative.houdini.in.stream=queue:islandora-connector-houdini
-derivative.houdini.service.url=http://127.0.0.1:8000/houdini/convert
+derivative.houdini.service.url=http://127.0.0.1/houdini/convert
 derivative.houdini.concurrent-consumers=1
 derivative.houdini.max-concurrent-consumers=4
 derivative.houdini.async-consumer=true
 
 derivative.fits.enabled=true
 derivative.fits.in.stream=queue:islandora-connector-fits
-derivative.fits.service.url=http://127.0.0.1:8000/crayfits
+derivative.fits.service.url=http://127.0.0.1/crayfits
 derivative.fits.concurrent-consumers=2
 derivative.fits.max-concurrent-consumers=2
 derivative.fits.async-consumer=false
@@ -267,7 +318,8 @@ http.additional_options=authMethod=Basic,authUsername=Jim,authPassword=1234
 
 These will be added to ALL http endpoint requests.
 
-**Note**: We are currently running Camel 3.7.6, some configuration parameters on the above linked page might not be supported.
+!!! note "Check Camel Configuration Parameters"
+    We are currently running Camel 3.7.6, some configuration parameters on the above linked page might not be supported.
 
 ### Deploying/Running
 
@@ -306,7 +358,7 @@ Description=Alpaca service
 After=network.target
 
 [Service]
-Type=forking
+Type=simple
 ExecStart=java -jar /opt/alpaca/alpaca.jar -c /opt/alpaca/alpaca.properties
 ExecStop=/bin/kill -15 $MAINPID
 SuccessExitStatus=143
@@ -316,4 +368,4 @@ Restart=always
 WantedBy=default.target
 ```
 
-Now you can start the service by running `systemctl start alpaca` and set it to come up when the system reboots with `systemctl enable alpaca`.
+Now you can start the service by running `sudo systemctl start alpaca` and set it to come up when the system reboots with `sudo systemctl enable alpaca`. Check the status by running `sudo systemctl status alpaca`.

docs/installation/manual/installing-composer-drush-and-drupal.md

@@ -5,10 +5,19 @@
 
 ## In this section, we will install:
 
+- [cURL](https://curl.se/) is used by composer to efficiently download libraries
 - [Composer](https://getcomposer.org/) at its current latest version, the package manager that will allow us to install PHP applications
 - Either the [Islandora Starter Site](https://github.com/Islandora/islandora-starter-site/), or the [Drupal recommended-project](https://www.drupal.org/docs/develop/using-composer/starting-a-site-using-drupal-composer-project-templates#s-drupalrecommended-project), which will install, among other things:
-    - [Drush 10](https://www.drush.org/) at its latest version, the command-line PHP application for running tasks in Drupal
-    - [Drupal 9](https://www.drupal.org/) at its latest version, the content management system Islandora uses for content modelling and front-end display
+    - [Drush](https://www.drush.org/) at its latest version, the command-line PHP application for running tasks in Drupal
+    - [Drupal](https://www.drupal.org/) at its latest version, the content management system Islandora uses for content modelling and front-end display
+
+## Install cURL
+
+cURL may already be installed. Check by running `curl --version`. If it isn't, install it:
+
+```bash
+sudo apt install curl
+```
 
 ## Install Composer
 
@@ -30,14 +39,21 @@ At this point, you have the option of using the [Islandora Starter Site](https:/
 and configurations which function "out of the box," or build a clean stock Drupal via the Drupal Recommended Project and install
 Islandora modules as you desire.
 
+On a default Ubuntu install the `/var/www` directory is owned by root, but we want the webserver to control this space, so we'll give it ownership:
+
+```bash
+sudo chown -R www-data: /var/www
+```
+
+
 ### Option 1: Create a project using the Islandora Starter Site
 
-Navigate to the folder where you want to put your Islandora project (in our case `/var/www`), and
-create the Islandora Starter Site:
+Navigate to the folder where you want to put your Islandora project (in our case `/var/www/html`). You can give your site any name you like, but for these instructions we will simply call it "drupal":
 
 ```bash
-cd /var/www
-composer create-project islandora/islandora-starter-site
+cd /var/www/html
+sudo -u www-data mkdir drupal
+sudo -u www-data composer create-project islandora/islandora-starter-site drupal
 ```
 
 This will install all PHP dependencies, including Drush, and scaffold the site.
@@ -46,12 +62,12 @@ Drush is not accessible via `$PATH`, but is available using the command `compose
 
 ### Option 2: Create a basic Drupal Recommended Project
 
-Navigate to the folder where you want to put your Drupal project (in our case `/var/www`), and
+Navigate to the folder where you want to put your Drupal project (in our case `/var/www/html`), and
 create the Drupal Recommended Project:
 
 ```bash
-cd /var/www
-composer create-project drupal/recommended-project my-project
+cd /var/www/html
+sudo -u www-data composer create-project drupal/recommended-project drupal
 ```
 
 
@@ -69,12 +85,13 @@ Listen 80
 
 Remove everything but the "Listen 80" line. You can leave the comments in if you want.
 
-`/etc/apache2/sites-enabled/000-default.conf | root:root/777`
+Create a drupal virtual host:
+`/etc/apache2/sites-available/islandora.conf | root:root/644`
 ```xml
 <VirtualHost *:80>
   ServerName SERVER_NAME
-  DocumentRoot "/opt/drupal/web"
-  <Directory "/opt/drupal/web">
+  DocumentRoot "/var/www/html/drupal/web"
+  <Directory "/var/www/html/drupal/web">
     Options Indexes FollowSymLinks MultiViews
     AllowOverride all
     Require all granted
@@ -87,33 +104,30 @@ Remove everything but the "Listen 80" line. You can leave the comments in if you
 - `SERVER_NAME`: `localhost`
     - For a development environment hosted on your own machine or a VM, `localhost` should suffice. Realistically, this should be the domain or IP address the server will be accessed at.
 
-Restart the Apache 2 service to apply these changes:
+Set permissions and enable the virtual host:
 
 ```bash
 sudo systemctl restart apache2
+sudo a2ensite islandora.conf
+sudo systemctl reload apache2
 ```
-## Prepare the PostgreSQL database
+## Prepare the MySQL database
+
+We're going to create a user in MySQL for this Drupal site. Then create a database that we can use to install Drupal.
+
+The following values can (and in the case of the password, *should*) be changed to local values.
 
-PostgreSQL roles are directly tied to users. We’re going to ensure a user is in place, create a role for them in PostgreSQL, and create a database for them that we can use to install Drupal.
+- `DRUPAL_DATABASE_NAME`: This will be used as the core database that Drupal is installed into
+- `MYSQL_USER_FOR_DRUPAL`: Specifically, this is the user that will connect to the MySQL database being created, not the user that will be logging into Drupal
+- `MYSQL_PASSWORD_FOR_DRUPAL`:  This should be a secure password; it’s recommended to use a password generator to create this such as the one provided by [random.org](https://www.random.org/passwords/)
 
 ```bash
-# Run psql as the postgres user, the only user currently with any PostgreSQL
-# access.
-sudo -u postgres psql
-# Then, run these commands within psql itself:
-create database DRUPAL_DB encoding 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8' TEMPLATE template0;
-create user DRUPAL_DB_USER with encrypted password 'DRUPAL_DB_PASSWORD';
-grant all privileges on database DRUPAL_DB to DRUPAL_DB_USER;
-# Then, quit psql.
-\q
+sudo mysql -u root
+CREATE DATABASE [DRUPAL_DATABASE_NAME];
+CREATE USER '[MYSQL_USER_FOR_DRUPAL]'@'localhost' IDENTIFIED BY '[MYSQL_PASSWORD_FOR_DRUPAL]';
+GRANT ALL PRIVILEGES ON [DRUPAL_DATABASE_NAME].* TO '[MYSQL_USER_FOR_DRUPAL]'@'localhost';
+exit
 ```
-- `DRUPAL_DB`: `drupal9`
-    - This will be used as the core database that Drupal is installed into
-- `DRUPAL_DB_USER`: `drupal`
-    - Specifically, this is the user that will connect to the PostgreSQL database being created, not the user that will be logging into Drupal
-- `DRUPAL_DB_PASSWORD`: `drupal`
-    - This should be a secure password; it’s recommended to use a password generator to create this such as the one provided by [random.org](https://www.random.org/passwords/)
-
 
 ## Install Drupal using Drush
 
@@ -122,13 +136,18 @@ The Drupal installation process can be done through the GUI in a series of form
 ### Option 1: Site install the Starter Site with existing configs
 
 Follow the instructions in the [README of the Islandora Starter Site](https://github.com/Islandora/islandora-starter-site/#usage).
-The steps are not reproduced here to remove redundancy. When this installation is done, you'll have a starter site ready-to-go. Once you set up the external services in the next sections, you'll need to configure Drupal to know where they are.
+The steps are not reproduced here to remove redundancy. But specifically,
+
+1. Configure the database connection information (see the section above) and fedora flysystem in `/var/www/html/drupal/web/sites/default/settings.php`.
+2. Install the site using `sudo -u www-data composer exec -- drush site:install --existing-config`.
+
+When this installation is done, you'll have a starter site ready-to-go. Once you set up the external services in the next sections, you'll need to configure Drupal to know where they are.
 
 ### Option 2: Site install the basic Drupal Recommended Project
 
 ```bash
 cd /var/www/drupal
-drush -y site-install standard --db-url="pgsql://DRUPAL_DB_USER:DRUPAL_DB_PASSWORD@127.0.0.1:5432/DRUPAL_DB" --site-name="SITE_NAME" --account-name=DRUPAL_LOGIN --account-pass=DRUPAL_PASS
+sudo -u www-data drush -y site-install standard --db-url="mysql://MYSQL_USER_FOR_DRUPAL:MYSQL_PASSWORD_FOR_DRUPAL@127.0.0.1:3306/DRUPAL_DATABASE_NAME" --site-name="SITE_NAME" --account-name=DRUPAL_LOGIN --account-pass=DRUPAL_PASS
 ```
 This uses the same parameters from the above step, as well as: