Skip to content

Commit

Permalink
Updating Manual Install Instructions Based on Feedback from slangerx (#…
Browse files Browse the repository at this point in the history 
…2328)

* work-in-progress

* Alpaca & Crayfish updates

* Postgres→MySQL

* add missing user to chown

* update note formatting

* fix note formatting

* update note formatting

* change note to warning
  • Loading branch information
@seth-shaw-asu
seth-shaw-asu authored Jul 17, 2024
1 parent 11404ab commit 5ba7739
Show file tree
Hide file tree
Showing 9 changed files with 423 additions and 326 deletions.
4 changes: 2 additions & 2 deletions docs/installation/manual/configuring-drupal.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'] = [
Expand Down
104 changes: 78 additions & 26 deletions docs/installation/manual/installing-alpaca.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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`.
85 changes: 52 additions & 33 deletions docs/installation/manual/installing-composer-drush-and-drupal.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
Expand All @@ -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
```


Expand All @@ -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
Expand All @@ -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

Expand All @@ -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:

Expand Down
Loading

0 comments on commit 5ba7739

Please sign in to comment.