Skip to content

Commit dff94af

Browse files
StrubTStrubT
committed
add brief introduction and advanced configuration documentation
1 parent a235472 commit dff94af

5 files changed

Lines changed: 132 additions & 73 deletions

File tree

‎README.md‎

Lines changed: 23 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ This is the code of the **Executor** component of the project **Progressor - The
66

77
These instructions are written for *Ubuntu* 16.04 LTS.
88

9-
The goal is to install the Executor in `/opt/Executor/` and run it as a Docker container.
9+
The goal is to install the **Executor** in `/opt/Executor/` and run it as a Docker container.
1010

1111
### Server Setup
1212

@@ -33,105 +33,55 @@ The goal is to install the Executor in `/opt/Executor/` and run it as a Docker c
3333
environment=KOTLIN_HOME="/kotlinc"
3434
```
3535

36+
* If you need to override the default settings, please refer to the detailed [configuration information](doc/ExecutorConfig.md).
37+
3638
1. Make *Supervisor* start when the server boots: `sudo systemctl enable supervisor`
3739
1. Start the service by executing `sudo service supervisor start`
3840
1. Reload *Supervisor* configuration by running `sudo supervisorctl reread`
3941
1. and `sudo supervisorctl update`
4042

4143
### Uploading the Executor JAR and Building the Docker Image
4244

43-
1. If you built the Executor jar from this repo, rename it to `ProgressorExecutor.jar` and upload it to your server in `/opt/Executor/`, otherwise download the pre-compiled one:
45+
1. If you built the **Executor** *JAR* from this repo, rename it to `ProgressorExecutor.jar` and upload it to your server in `/opt/Executor/`, otherwise download the pre-compiled one:
4446
1. `cd /opt/Executor/`
4547
1. `wget https://github.com/Progressor/ProgressorMeteor/raw/master/bin/ProgressorExecutor.jar`
4648
1. If you modified the [*Dockerfile*](src/main/docker/Dockerfile), upload it to your server in `/opt/Executor/`, otherwise download the pre-compiled one:
4749
1. `cd /opt/Executor`
4850
1. `wget https://raw.githubusercontent.com/Progressor/ProgressorExecutor/master/src/main/docker/Dockerfile`
49-
1. On the server, still in `/opt/Executor`, build the *Docker* image used by the Executor by running `docker build -t progressor/executor .`
51+
1. On the server, still in `/opt/Executor`, build the *Docker* image used by the **Executor** by running `docker build -t progressor/executor .`
5052

51-
The *Executor* will use this image to create one container per request.
53+
The **Executor** will use this image to create one container per request.
5254
After the request has been processed, the container is stopped and immediately deleted.
5355

5456
That way we make sure the different requests never interfere with each other.
5557

56-
# Building the Executor from source
57-
## Maven
58+
### Building the Executor From Source
5859

5960
This repository contains a [*Maven*](https://maven.apache.org/) project created using [*IntelliJ IDEA*](https://www.jetbrains.com/idea/).
6061

61-
Executor won't work properly if Apache Thrift files have not been generated. Luckily, Maven generates these files for us when you build the project, so before you run the Executor run it as a Maven build: *mvn -clean -package*
62-
63-
### Dependencies
64-
65-
This project has four *Maven* dependencies:
66-
67-
1. [org.apache.thrift:libthrift:0.9.3](http://mvnrepository.com/artifact/org.apache.thrift/libthrift/0.9.3)
68-
for *Apache Thrift*
69-
1. [org.json:json:20151123](http://mvnrepository.com/artifact/org.json/json/20151123)
70-
for *JSON* decoding
71-
1. [org.slf4j:slf4j-simple:1.7.13](http://mvnrepository.com/artifact/org.slf4j/slf4j-simple/1.7.13)
72-
for logging
73-
1. [org.testng:testng:RELEASE](http://mvnrepository.com/artifact/org.testng/testng)
74-
for unit tests
75-
76-
# Docker
77-
78-
[*Docker*](https://www.docker.com/) is active by default on Linux distributions. On Windows it is deactivated by default, since you're not able to use the Executor with *Docker* on Windows.
79-
The created *Docker* image Tag is named `progressor/executor`.
80-
If you decide not to use *Docker*, use the following `-docker false`.
81-
82-
Be aware that not using *Docker* requires you to install all the compilers of the languages you want to support on your server.
83-
If you use *Docker* you need to install the compilers in your *Docker* image. To do that, you need to adjust the Dockerfile and rebuild your image.
84-
85-
# Programming Languages
86-
87-
The **Executor** currently supports five programming languages.
88-
89-
To use the languages, the following compilers (and other tools) need to be installed and available in the **PATH**.
90-
91-
1. *Java*: `javac` and `java`
92-
1. *C/C++*: `g++`
93-
1. *C#*: `csc` (Windows) or `msc` (Linux)
94-
1. *Kotlin*: `kotlinc` and `kotlin`
95-
1. *Python*: `python` (Windows)
96-
97-
As already mentioned, if you are using *Docker* these compilers need to be installed inside the *Docker* image via the Dockerfile.
98-
Java is the only exception, since it is needed inside the *Docker* image as well as on the server to run the executor.
99-
100-
### Java
101-
102-
Support for *Java SE* version 8 is required.
103-
104-
The *Java Developer Toolkit* (JDK) can be downloaded from the [official *Oracle* downloads page](http://www.oracle.com/technetwork/java/javase/downloads/).
105-
106-
### C/C++
107-
108-
This projects targets the [*GNU Compiler Collection* (GCC)](https://gcc.gnu.org/).
109-
Support for *C++11* is required.
62+
*Maven* can easily be [downloaded](https://maven.apache.org/download.cgi) and [installed](https://maven.apache.org/install.html) on any platform.
63+
But it is also included in many IDEs like [*IntelliJ IDEA*](https://www.jetbrains.com/idea/), [*NetBeans*](https://netbeans.org/) and others.
11064

111-
* For Linux, install *g++* using `apt-get install g++`
112-
* For Windows, the following packages are available:
113-
* [*MinGW*](http://www.mingw.org/), which can be downloaded from [*sourceforge*](https://sourceforge.net/projects/mingw/files/).
114-
* A [x64 version](http://mingw-w64.org/) is available on a [dedicated site](http://mingw-w64.org/doku.php/download/win-builds).
115-
* [*Cygwin*](http://sourceware.org/cygwin/), which can be downloaded from their home page.
65+
The dependencies are outlined in a [separate document](doc/ExecutorDependencies.md).
11666

117-
### C# #
67+
You can build the project by executing `mvn clean package -Dmaven.test.skip=true` which will create the executable `target/ProgressorExecutor-1.0-jar-with-dependencies.jar`.
11868

119-
* On Windows, the C# compiler is already included in most recent Windows operatiog systems. Make sure that the *PATH* environment variable is set to `C:\WINDOWS\Microsoft.NET\Framework\v[your version number]\csc.exe.`
120-
* If this directory does not exist, you can download the [*.NET Core*](https://www.microsoft.com/net/download)
121-
* On Linux, [*Mono*](http://www.mono-project.com/) can be downloaded on their [download page](http://www.mono-project.com/download/).
69+
This statement will do the following:
12270

123-
#### Kotlin
71+
1. It will clean the workspace and remove any files left over from previous builds.
72+
1. It will generate *Java*-specific [*Apache Thrift*](https://thrift.apache.org/) code based on the language-independent interface definition in `src/main/thrift/executor.thrift`.
73+
1. It will skip the tests as you may not have properly set up your development machine to test all supported programming languages.
74+
1. It will build the application.
75+
1. It will generate two *JAR* files: one slim version (without the dependencies included) and one with all the dependencies included which you can then copy and use wherever you like.
12476

125-
For [*Kotlin*](http://kotlinlang.org/), a [stand-alone compiler](http://kotlinlang.org/docs/tutorials/command-line.html) can be downloaded from [*GitHub*](https://github.com/JetBrains/kotlin/releases/latest).
77+
## Introduction
12678

127-
### Python
79+
The **Executor** is a *Java* application that receives requests from the **Progressor** web application using *Apache Thrift*.
12880

129-
* On Linux, Python 3 install using *apt-get install python3*
130-
* On Windows, download [*Python 3*](https://www.python.org/downloads/release/python-351/) and install it.
81+
The actual application logic is completely separated from the *Apache Thrift* layer and has its own public API that can be used to [extend](doc/ExecutorConfig.md#extensibility) the **Executor**.
13182

132-
## Extensibility
83+
![public Executor API](doc/images/ExecutorAPI.png)
13384

134-
The **Executor** uses a [ServiceLoader](http://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) to load the different code executors at runtime.
85+
Additionally, the project contains two abstract classes that can be reused to easily implement a new programming language.
13586

136-
New languages can be supported by simply implementing the service *ch.bfh.progressor.executor.api.CodeExecutor* and making it discoverable by the **Executor**.
137-
Additional information can be found in the [Java SE API Specification](http://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html).
87+
![abstract Code Executors](doc/images/ExecutorCodeExecutor.png)

‎doc/ExecutorConfig.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Progressor - Advanced Executor Configuration Options
2+
3+
## Command-Line Arguments
4+
5+
The **Executor** accepts a number of command-line arguments:
6+
7+
* `-p port` or `-port port` will override the default port (9001).
8+
* `-c [false|no]` or `-cleanup [false|no]` will prevent temporary files (e.g. generated code files, compiled executables or *Docker* containers) from being deleted.
9+
* `-d [true|yes]` or `-docker [true|yes]` has no effect because because cleanup is enabled by default.
10+
* `-d [false|no]` or `-docker [false|no]` will disable *Docker* support on Linux.
11+
* `-d [true|yes]` or `-docker [true|yes]` has no effect because because *Docker* is enabled by default on Linux.
12+
If invoked on Windows, the application will abort because this feature is not yet supported.
13+
* `-t [true|yes]` or `-test [true|yes]` will run a test client instead of the server (request handler).
14+
* `-t [false|no]` or `-test [false|no]` has no effect because server is the standard mode.
15+
* `-h hostname` or `-host hostname` can be used to test an instance different from the local one.
16+
17+
## Extensibility
18+
19+
The **Executor** uses a [ServiceLoader](http://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) to load the different code executors at runtime.
20+
21+
New languages can be supported by simply implementing the service *ch.bfh.progressor.executor.api.CodeExecutor* and making it discoverable by the **Executor**.
22+
Additional information can be found in the [Java SE API Specification](http://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html).

‎doc/ExecutorDependencies.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Progressor - Executor Dependencies
2+
3+
This project has five *Maven* dependencies:
4+
5+
1. [org.apache.thrift:libthrift:0.9.3](http://mvnrepository.com/artifact/org.apache.thrift/libthrift/0.9.3)
6+
for *Apache Thrift*
7+
1. [org.json:json:20151123](http://mvnrepository.com/artifact/org.json/json/20151123)
8+
for *JSON* decoding
9+
1. [org.slf4j:slf4j-simple:1.7.13](http://mvnrepository.com/artifact/org.slf4j/slf4j-simple/1.7.13)
10+
for logging
11+
1. [org.testng:testng:RELEASE](http://mvnrepository.com/artifact/org.testng/testng)
12+
for unit tests
13+
1. [commons-io:commons-io:2.5](http://mvnrepository.com/artifact/commons-io/commons-io/2.5)
14+
for proper *UTF-8* support on streams
15+
16+
## Docker
17+
18+
[*Docker*](https://www.docker.com/) support is activated by default on Linux distributions. On any other platform, *Docker* is not yet supported.
19+
The created *Docker* image is tagged `progressor/executor`.
20+
If you decide not to use *Docker*, use the following `-docker false`.
21+
22+
Be aware that not using *Docker* requires you to install all the compilers of the languages you want to support on your server.
23+
If you use *Docker* you need to install the compilers in your *Docker* image. To do that, you need to adjust the *Dockerfile* and rebuild your image.
24+
25+
## Programming Languages
26+
27+
The **Executor** currently supports five programming languages.
28+
29+
To use the languages, the following compilers (and other tools) need to be installed and available in the **PATH**.
30+
31+
1. *Java*: `javac` and `java`
32+
1. *C/C++*: `g++`
33+
1. *C#*: `csc` (Windows) or `msc` and `mono` (Linux)
34+
1. *Python*: `python` (Windows)
35+
1. *JavaScript* ([Node.js](https://nodejs.org/)): `node`
36+
1. *PHP*: `php`
37+
1. *Kotlin*: `kotlinc` and `kotlin` (these scripts are actually simulated until a security issue can be solved with *Java 9*)
38+
1. *VB.NET*: `vbc` (Windows) or `vbnc` and `mono` (Linux)
39+
40+
As already mentioned, if you are using *Docker* these compilers need to be installed inside the *Docker* image via the *Dockerfile*.
41+
Java is the only exception, since it is needed inside the *Docker* image as well as on the server to run the **Executor**.
42+
43+
### Java
44+
45+
Support for *Java 8* is required.
46+
47+
The *Java Developer Toolkit* (JDK) can be downloaded from the [official *Oracle* downloads page](http://www.oracle.com/technetwork/java/javase/downloads/).
48+
49+
### C/C++
50+
51+
This projects targets the [*GNU Compiler Collection* (GCC)](https://gcc.gnu.org/).
52+
Support for *C++11* is required.
53+
54+
* For Linux, install *g++* using `apt-get install g++`
55+
* For Windows, the following packages are available:
56+
* [*MinGW*](http://www.mingw.org/), which can be downloaded from [*sourceforge*](https://sourceforge.net/projects/mingw/files/).
57+
* A [x64 version](http://mingw-w64.org/) is available on a [dedicated site](http://mingw-w64.org/doku.php/download/win-builds).
58+
* [*Cygwin*](http://sourceware.org/cygwin/), which can be downloaded from their home page.
59+
60+
### C# #
61+
62+
* On Windows, the C# compiler is already included in most recent Windows operating systems. Make sure that the *PATH* environment variable is set to `C:\WINDOWS\Microsoft.NET\Framework\v[your version number]\csc.exe.`
63+
* If this directory does not exist, you can download the [*.NET Core*](https://www.microsoft.com/net/download).
64+
* On Linux, [*Mono*](http://www.mono-project.com/) can be downloaded on their [download page](http://www.mono-project.com/download/).
65+
66+
### Python
67+
68+
* On Linux, Python 3 install using *apt-get install python3*
69+
* On Windows, download [*Python 3*](https://www.python.org/downloads/release/python-351/) and install it.
70+
71+
### JavaScript
72+
73+
Install [Node.js](https://nodejs.org/) version *6.x.x* as any version below will not fully comply with *ES6*.
74+
75+
### PHP
76+
77+
Install [PHP](http://php.net/downloads.php) ([Windows](http://windows.php.net/download#php-7.0)) version 7.x.x.
78+
79+
### Kotlin
80+
81+
For [*Kotlin*](http://kotlinlang.org/), a [stand-alone compiler](http://kotlinlang.org/docs/tutorials/command-line.html) can be downloaded from [*GitHub*](https://github.com/JetBrains/kotlin/releases/latest).
82+
83+
### VB.NET
84+
85+
* On Windows, the VB.NET compiler is already included in most recent Windows operating systems. Make sure that the *PATH* environment variable is set to `C:\WINDOWS\Microsoft.NET\Framework\v[your version number]\vbc.exe.`
86+
* If this directory does not exist, you can download the [*.NET Core*](https://www.microsoft.com/net/download).
87+
* On Linux, [*Mono*](http://www.mono-project.com/) can be downloaded on their [download page](http://www.mono-project.com/download/).

‎doc/images/ExecutorAPI.png‎

266 KB
Loading

‎doc/images/ExecutorCodeExecutor.png‎

300 KB
Loading

0 commit comments

Comments
 (0)