Hilary is the back-end for the Open Academic Environment
If you're looking to install the OAE project the hard way (not recommended), check out this page and then go the the Setup section below. If not, read along.
This guide will install OAE locally for a development setup. Node is required on the host machine whereas the remaining servers will run as docker containers.
The recommended way to install docker is to follow the official guide at https://docs.docker.com/engine/installation/. Make sure you have docker version >= 17.x and docker-compose version >= 1.6.0 before you proceed to cloning the repos. Check your versions by running the following commands:
$ docker -v
Docker version 17.03.0-ce, build 60ccb2265
$ docker-compose -v
docker-compose version 1.11.2, build dfed245
Also, don't forget the post-install instructions if you're using linux.
git clone https://github.com/oaeproject/Hilary.git && cd Hilary
git submodule init
git submodule update
cd 3akai-ux && git checkout master # because HEAD is detached after pulling submodules by default
If you accept the following directory structure, docker-compose will work out of the box.
<some-local-path>
|-- Hilary
|-- 3akai-ux
|-- tmp
|-- previews
|-- uploads
|-- files
|-- data
|-- elasticsearch
|-- cassandra
|-- etherpad
If you want to use different (local) paths, make sure to change container volumes accordingly on docker-compose.yml:
# this will build the hilary:latest image and create all containers
docker-compose up --no-start --build oae-cassandra oae-redis oae-rabbitmq oae-elasticsearch oae-hilary
NOTE: if the previous step fails due to network problems, try changing the DNS server to Google's: 8.8.8.8 or 8.8.4.4. In order to do this, either use your operating system's settings or do it via the command line interface by editing /etc/resolv.conf and making sure these two lines are on top:
nameserver 8.8.8.8
nameserver 8.8.4.4
In order to install dependencies for the frontend and the backend, we need to run a one-off command for each:
npm install # install dependencies locally for Hilary
cd 3akai-ux && npm install" # install dependencies for 3akai-ux
If we're looking to use HTTPS via nginx, first we need to create the SSL certificate. You can do do that by running:
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout 3akai-ux/nginx/nginx-selfsigned.key -out 3akai-ux/nginx/nginx-selfsigned.crt
This will create two new files: 3akai-ux/nginx/nginx-selfsigned.key and 3akai-ux/nginx/nginx-selfsigned.crt.
Then, run the following command:
openssl dhparam -out 3akai-ux/nginx/dhparam.pem 2048
This may take a few minutes, but when it's done you will have the file nginx/dhparam.pem that you can use in your configuration.
--
Before moving on to the next step, make sure these three files exist otherwise there will be errors.
Open the file nginx.conf.docker and make sure these lines:
...
server oae-hilary:2000;
...
server oae-hilary:2001;
...
..become:
...
server 172.20.0.1:2000; # `172.20.0.1` is the IP address of the host machine, which can be obtained by running `/sbin/ip route|awk '/default/ { print $3 }'` from any container (e.g. `docker exec -it oae-nginx sh`).
...
server 172.20.0.1:2001;
...
If you're using mac osx, you'll need to use the external IP address (e.g. en0) instead of the docker0 IP address for oae-nginx to access Hilary, like this:
...
server 192.168.1.2:2000; # assuming 192.168.1.2 is the external network IP address
...
server 192.168.1.2:2001; # assuming 192.168.1.2 is the external network IP address
...
Also, don't forget that running Hilary locally implies installing several other packages, namely soffice (libreoffice), pdftotext and pdf2htmlEX. You can find instructions on how to do this here. If you can't get pdf2htmlEX installed on your system, you may use a docker container instead, by replacing the config.previews.pdf2htmlEX.binary setting to docker-compose run --rm oae-pdf2htmlex pdf2htmlEX. On mac osx you can find all three in homebrew.
Now run docker-compose up -d oae-cassandra oae-redis oae-rabbitmq oae-elasticsearch oae-etherpad and then docker-compose logs -f to check the logs. You may then run nodemon app.js | bunyan (or npm start for short) locally on the terminal to start the server.
The service names and description are in the docker-compose.yml file.
To start and stop all containers at once, run docker-compose up and docker-compose down respectively. Check docker-compose documentation for more information.
If you need to rebuild the hilary:latest docker image, try running docker build -f Dockerfile -t hilary:latest ..
If you need to tail the logs of a specific server for debugging, try running docker logs -f oae-cassandra (for the oae-cassandra service).
If you're having network problems, run docker network inspect bridge for check container network configuration or docker inspect oae-hilary to take a look at oae-hilary container details.
--
In order to set up twitter authentication, you'll need to set your twitter dev account environment variables like this:
export TWITTER_KEY="<your key here>"
export TWITTER_SECRET"="<your secret here>"
Same thing goes for google auth and facebook auth. The environment variables for each are:
export GOOGLE_CLIENT_ID=""
export GOOGLE_CLIENT_SECRET=""
export FACEBOOK_APP_ID=""
export FACEBOOK_APP_SECRET=""
This is enough to run all the tests locally in a dev environment. For production purposes, all environment variables can and should be overwritten by the admin in the tenant configuration form.
OAE is a multi-tenant system that discriminates the tenant by the host name with which you are accessing the server. In order to support the "Global Tenant" (i.e., the tenant that hosts the administration UI) and a "User Tenant", you will need to have at least 2 different host names that point to your server. To do this, you will need to add the following entries to your /etc/hosts file:
127.0.0.1 admin.oae.com
127.0.0.1 tenant1.oae.com
Where admin.oae.com is the hostname that we will use to access the global administration tenant and tenant1.oae.com would be one of many potential user tenant hosts. After making this change, you should now be able to visit http://admin.oae.com \o/
This same DNS information must be made explicit in the docker-compose.yml file, to make sure that the oae-hilary container can connect to the oae-nginx container holding HTTP server (for instance, for preview processing purposes). Go to the file and look for the following section:
extra_hosts:
- "admin.oae.com:172.20.0.9"
- "tenant1.oae.com:172.20.0.9"
As you see, we already included both admin.oae.com and tenant1.oae.com, both associated with the oae-nginx static IP. If you're looking to add an extra host, say, tenant2.oae.com, then you should add the following line and you're good to go:
- "tenant2.oae.com:172.20.0.9"
When you start the server, all data schemas will be created for you if they don't already exist. A global administrator user and global administration tenant will be ready for you as well. You can use these to create a new user tenant that hosts the actual OAE user interface.
- Visit http://admin.oae.com/ (substitute "admin.oae.com" with the administration host you configured in
/etc/hosts) - Log in with username and password:
administrator/administrator - Click the "Tenants" header to open up the actions
- Click "Create tenant"
- Choose an alias (a short, unique 2-5 character alphanumeric string such as "oae"), and a name of your liking.
- For the Host field, use the host you configured for your user tenant in
/etc/hosts(e.g., "tenant1.oae.com") - Click "Create new tenant"
You can now access the user tenant by their host http://tenant1.oae.com and start creating new users.
To create a new user, use either the Sign Up link at the top left, or the Sign In link at the top right.
Tip: OAE requires that users have an email address that is verified VIA an email that is sent to the user. To avoid the requirement of having a valid email server configuration, you can instead watch the app server logs when a user is created or their email address is updated. When config.email.debug is set to true in config.js, the content of the verification email can be seen in the logs, and you can copy/paste the email verification link from the log to your browser to verify your email. The URL will look similar to: http://tenant1.oae.com/?verifyEmail=abc123
We're looking forward to seeing your contributions to the OAE project!
To run tests just make sure you have installed all dependencies (npm i) and run npm test. To run tests on a specific module, just append its name as follows: npm run test-module -- oae-principals.
If you still can't see the Web interface correctly by the time the containers start, it might be due to Hilary starting before Cassandra was available. This usually results in 502 Service unavailable pages. We recommend to start hilary again to make sure it boots after cassandra is accepting connections: docker-compose restart oae-hilary. This is something we're looking to fix in the future.
The project website can be found at http://www.oaeproject.org. The project blog will be updated with the latest project news from time to time.
The mailing list used for Apereo OAE is [email protected]. You can subscribe to the mailing list at https://groups.google.com/a/apereo.org/d/forum/oae.
Bugs and other issues can be reported in our issue tracker. Ideas for new features and capabilities can be suggested and voted for in our UserVoice page.