Skip to content

Commit f57ec47

Browse files
xchopinxchopin
committed
docs(en): add administrator guide
1 parent 81b3597 commit f57ec47

File tree

7 files changed

+219
-0
lines changed

7 files changed

+219
-0
lines changed

‎docs/en/administrator/docker.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Running OpenLRW with Docker
2+
3+
OpenLRW runs easily with [Docker](https://www.docker.com).
4+
5+
6+
In the future this could be used for production but currently it's just set up for development
7+
8+
This is built with regular `docker-compose build` then `docker-compose up -d`. `docker-compose down` will bring this down. The redis data is stored in a local folder ./redis-data. Delete this folder to delete the data.
9+
10+
An container running Mongo and this application will be started.
11+
12+
## Get your API
13+
14+
The API can be retrieved similarly to above
15+
16+
`docker run -it --link openlrw_mongo --net openlrw_net --rm mongo mongo --host mongo test -u root -p example --eval "db.mongoOrg.find().pretty()" | grep \"api`

‎docs/en/administrator/helpers.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Helpers
2+
3+
4+
## Find OpenLRW API Key and Secret
5+
The OpenLRW admin user interface is under development so you'll have to find your API key and secret by directly accessing your MongoDB instance. Follow the commands below to find your key and secret. The commands assume that you are able to access MongoDB via the command line and that you are using the default database name (if not, you would have changed this manually in openlrw).
6+
7+
```javascript
8+
> mongo
9+
> use test
10+
> db.mongoOrg.find().pretty()
11+
12+
{
13+
"_id" : ObjectId("objid"),
14+
"_class" : "unicon.matthews.oneroster.service.repository.MongoOrg",
15+
"apiKey" : "abcdef",
16+
"apiSecret" : "123456",
17+
"tenantId" : "583ce4076f03bb1f88bee0ea",
18+
"org" : {
19+
"sourcedId" : "1f03f835-d992-4301-8e5c-5ad55e6489f5",
20+
"status" : "active",
21+
"metadata" : {
22+
"https://matthews/tenant" : "583ce4076f03bb1f88bee0ea"
23+
},
24+
"dateLastModified" : ISODate("2016-11-29T02:12:23.757Z"),
25+
"name" : "DEFAULT_ORG",
26+
"type" : "other"
27+
}
28+
}
29+
```
30+
31+
## Count events
32+
33+
```javascript
34+
> mongo
35+
> use test
36+
> db.mongoEvent.count()
37+
17813
38+
```
39+
40+
<br>
41+
42+
## Remove all events (testing only)
43+
44+
```javascript
45+
> mongo
46+
> use test
47+
> db.mongoEvent.count()
48+
17813
49+
> db.mongoEvent.remove({})
50+
WriteResult({ "nRemoved" : 17813 })
51+
> db.mongoEvent.count()
52+
0
53+
```
54+

‎docs/en/administrator/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Administrator Guide
2+
Installation, deployment and administration guide.
3+
4+
* [Requirements](requirements.md)
5+
* [Installation instructions](installation.md)
6+
* [Using a Production Setup](production.md)
7+
* [Running OpenLRW with Docker](docker.md)
8+
* [Helpers](helpers.md)

‎docs/en/administrator/installation.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Installation instructions
2+
First of all, check the requirements before going further.
3+
4+
## From the archive (stable version)
5+
*Well the project is in beta so.. there isn't stable version at the moment.*
6+
7+
## From the git repository (development version)
8+
> Note: This method will install the current development version, use at your own risk.
9+
10+
` $ git clone https://github.com/Apereo-Learning-Analytics-Initiative/OpenLRW.git `
11+
12+
##Run the application
13+
##### [Example of scripts for running the application in a production context](scripts.md)
14+
15+
16+

‎docs/en/administrator/production.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Using a Production Setup
2+
3+
> These followings instructions are our recommendations for using OpenLRW in a production setup.
4+
5+
## Create the following directory structure.
6+
7+
```
8+
/opt/
9+
└── openlrw/
10+
├── conf/
11+
├── lib/
12+
├── logs/
13+
├── run/
14+
├── src/
15+
├── build.sh
16+
└── run.sh
17+
```
18+
19+
## Add a specific user for running the application.
20+
21+
Create a user to run the application and make them owner of `/opt/openlrw/*` directories.
22+
```bash
23+
$ useradd -c "Boot User" boot
24+
$ chown -R boot:boot /opt/openlrw
25+
```
26+
27+
## Automated Start
28+
This following command can be useful for services like AWS Auto-Scale
29+
30+
```bash
31+
#!/bin/bash
32+
yum update -y
33+
bash
34+
cd /opt/openlrw
35+
rm /opt/openlrw/run/*.pid
36+
rm /opt/openlrw/*.log
37+
rm /opt/openlrw/logs/*.log
38+
su boot -c "sh build.sh"
39+
su boot -c "sh run.sh start"
40+
```
41+
42+
43+
## Possible Issues
44+
45+
You might experience very long startup times on some cloud hosted servers. This might be because of a shortage
46+
of entropy as a result of no keyboard, or mouse:
47+
48+
http://www.issihosts.com/haveged/
49+
50+
To rectify, install the above software (Ubuntu instructions):
51+
52+
```bash
53+
apt-get install haveged
54+
update-rc.d haveged defaults
55+
apt-get install rng-tools
56+
cat /dev/random | rngtest -c 1000
57+
```
58+
59+
If you are having troubles with certain caliper or xapi payloads, you can turn on http request loggging with the following:
60+
61+
```
62+
logging.level.org.springframework.web.filter.CommonsRequestLoggingFilter: DEBUG
63+
```

‎docs/en/administrator/requirements.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Requirements
2+
3+
* [Git](https://git-scm.com/)
4+
* [Java Development Kit 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)
5+
* [Maven 3](https://maven.apache.org/download.cgi)
6+
* [MongoDB 2.6+](https://docs.mongodb.com/manual/installation/)
7+
8+
> **⚠ Note** <br>
9+
The recommended operating system is GNU/Linux (Debian/Ubuntu/RHEL).

‎docs/en/administrator/scripts.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Scripts
2+
3+
Useful scripts for a production setup.
4+
5+
## Build Script (build.sh)
6+
From the `/opt/openlrw/` directory execute the build script to create the LRW executable.
7+
8+
```bash
9+
#!/bin/sh
10+
cd `dirname $0`
11+
cd src/OpenLRW
12+
git pull
13+
mvn -DskipTests=true clean install
14+
cp target/matthews-1.jar ../../lib/openlrw.jar
15+
```
16+
17+
## Run Script (run.sh)
18+
From the `/opt/openlrw/` directory execute the run script to start the application. Note you will need to update the script below with the appropriate MongoDB path. The application listens on port 9966.
19+
20+
```bash
21+
#!/bin/sh
22+
cd `dirname $0`
23+
APP_HOME="$PWD"
24+
PID_FILE=$APP_HOME/run/openlrw.pid
25+
JAR_PATH=$APP_HOME/lib/openlrw.jar
26+
27+
cd $APP_HOME
28+
29+
case "$1" in
30+
"start")
31+
if [ -f $PID_FILE ]; then
32+
exit 1
33+
fi
34+
java \
35+
-Dlogging.path=/opt/openlrw/logs/ \
36+
-Dspring.data.mongodb.uri=<!-- mongodb uri --> \
37+
-jar $JAR_PATH &
38+
echo $! > $PID_FILE
39+
;;
40+
"stop")
41+
if [ ! -f $PID_FILE ]; then
42+
exit 1
43+
fi
44+
kill `cat $PID_FILE`
45+
rm -f $PID_FILE
46+
;;
47+
*)
48+
echo "Usage: $0 start|stop"
49+
;;
50+
esac
51+
exit 0
52+
```
53+

0 commit comments

Comments
 (0)