Open Source Install Guide

OpenLucius is built on Drupal 9 as an install profile / distribution, currently (July 2020) all code is hosted on Github. When possible we'll host the install profile on Drupal.org, but right now we get all kinds of compatibility issues when hosted on there. Probably because of this issue, so when Drupal 9 stable is released we'll probably host it on Drupal.org.

Underneath you'll find:

  1. Three required steps to get OpenLucius up and running;
  2. Optional install steps.

1. Required install steps

These are the 3 necessary steps to get OpenLucius up and running:

1.1 Create your project with Composer

Open a terminal and create the project with the command underneath, change 'my_project_folder' the folder name of your choice.

composer create-project lucius-digital/openlucius-project:2.0.0-alpha3 MY_PROJECT_FOLDER

1.2 Install Drupal / OpenLucius profile

You can install OpenLucius just like installing a vanilla Drupal. If your web environment is set up, browse to your webroot ('my_project_folder/web') and you should get the install screen:

Drupal openlucius install

In the next screen choose the OpenLucius profile and walk through the install wizard:

OpenLucius Drupal install step 2

During the install, your first group 'General' will be added automatically, so at the end of the installation your screen should look sort of like this:

openlucius drupal install final screen

1.3 Drupal private files settings

All files are handled via Drupal's private files system, to handle access. So you'll have to set up private files.

2. Optional install steps

2.1 Node.js for realtimeness

To get the realtime chat working you'll have to set up Node.js:

2.1.1 Install npm packages

Get into the 'stream' folder:

cd my_project_folder/stream

Install node packages:

npm install
2.1.2 Start node.js server

Start the Node.js server for local development:

npm run devStart

Start the Node.js server on a production environment:

npm start

When running devStart, nodemon will assist. You should see something like this:

openlucius node.js run devstart

2.1.3 (!) Secure node.js production environment

To protect your node.js server against cross origin hacks (CORS), you'll have to configure this piece in server.js:

nodejs cors protection

More info about io.origins here and here

2.1.4 Set up node.js server in Drupal / OpenLucius admin settings

As final step, you'll have to enter the node.js server address, so Drupal / OpenLucius knows where it's at. As a Drupal administrator go to https://www.yourdomain.com/admin/settings/openlucius and enter the address:

nodejs server setting drupal / openlucius

2.1.5 Clear all caches

After you clear all Drupal caches, the real-time chat via Node.js should work.

2.2 Out-of-the box web environments

There are two web environment available:

  1. Docker (preferred)
  2. Drupal core's quick-start
2.2.1 Docker

The OpenLucius project provides a ready made Docker environment, there are a few steps you have to take to get it up and running. 

1. Generate SSL certificate

You can also find these 'SSL instructions' in:

/docker/docs/configure-https.md

Generate key by copy/pasting the command from configure-https.md:

docker generate key

Grant access to the key, for MacOS, double click on the generated cert.crt file:

docker cert file

After you double clicked the cert.crt file:

  1. Your Keychain Access window will open;
  2. In there find the 'openlucius.local' domain, double click on that;
  3. The screen underneath will open;
  4. In that screen choose 'always trust' for SSL:

SSL trust macos docker

When you close the Keychain Access window, it will ask you for your password to confirm permission, that's normal behaviour.

2. Add openlucius.local to your host file

This is documented in:

/docker/docs/configure-https.md

You can add it via the provided command, or add it manual in your hosts file:

sudo nano /etc/hosts

Make sure this is added and it's saved:

add local domain to host file macos

Then, to be sure, flush local dns cache:

sudo dscacheutil -flushcache

and

sudo killall -HUP mDNSResponder
3. Docker-compose up

To get the Docker environment up and running, from the project root enter in a terminal enter:

docker-compose up

==> Browse to https://openlucius.localhost

Enjoy! :)

(!) The mysql database in this Docker environment is not persistent by default, so make sure you create backups whenever you think is needed (!)

2.2.2 Drupal core's quick-start

You can quickly install OpenLucius with help of Drupal core's quick-start. You'll get it up and running in no time, but we did no testing in this environment, so currently it's not our preferred way of installing but very handy to take a quick peek. More info on Drupal's quick start here

From a terminal execute this command:

php your_project_folder/web/core/scripts/drupal quick-start openlucius --no-interaction

You should see something like the image underneath, your default browser will automatically open a tab with ready to test Drupal / OpenLucius.

Drupal quick start openlucius