README.md 7.76 KB
Newer Older
Taico Aerts's avatar
Taico Aerts committed
1
# Project Forum
Jesse Tilro's avatar
Jesse Tilro committed
2

Taico Aerts's avatar
Taico Aerts committed
3
4
[![Latest Release](https://gitlab.ewi.tudelft.nl/eip/projectforum/projectforum/-/badges/release.svg)](https://gitlab.ewi.tudelft.nl/eip/projectforum/projectforum/-/releases) [![coverage report](https://gitlab.ewi.tudelft.nl/eip/projectforum/projectforum/badges/master/coverage.svg)](https://gitlab.ewi.tudelft.nl/eip/projectforum/projectforum/-/commits/master) [![pipeline status](https://gitlab.ewi.tudelft.nl/eip/projectforum/projectforum/badges/master/pipeline.svg)](https://gitlab.ewi.tudelft.nl/eip/projectforum/projectforum/-/commits/master)

Taico Aerts's avatar
Taico Aerts committed
5
This repository contains the source code of the Project Forum application.
Taico Aerts's avatar
Taico Aerts committed
6
Project Forum has grown out of the second major version of the _Bachelor Project System (BEPSys)_ used at Delft University of Technology.  
Taico Aerts's avatar
Taico Aerts committed
7
8
The system was developed from scratch by David Alderliesten, Floris Doolaard, Jesse Tilro, and Niels Warnars in 2017 for their bachelor project.
For more information on the project, the technical report can be obtained from:
Jesse Tilro's avatar
Jesse Tilro committed
9
10
11
12
13

[https://repository.tudelft.nl/islandora/object/uuid:6f06fe0a-c9a7-4c5a-8bba-3d8de901be8a?collection=education](https://repository.tudelft.nl/islandora/object/uuid:6f06fe0a-c9a7-4c5a-8bba-3d8de901be8a?collection=education)

## Deployment

Taico Aerts's avatar
Taico Aerts committed
14
Check the [BEPSys Ansible](https://github.com/jessetilro/bepsys-ansible) private GitHub repository for all details on deploying Project Forum.
Jesse Tilro's avatar
Jesse Tilro committed
15

Taico Aerts's avatar
Taico Aerts committed
16
17
Deployment is done with a deployment script and with capistrano. See deploy.sh and config/deploy.rb.

18
19
20
21
22
## Technical Requirements
---

The project was built in Ruby on Rails, requiring the following:

Taico Aerts's avatar
Taico Aerts committed
23
* [__Rails__](https://github.com/rails/rails) version _6.1_.  
24
_This is a Ruby gem, of which the installation requires:_
Taico Aerts's avatar
Taico Aerts committed
25
26
 * [__Ruby__](https://www.ruby-lang.org/en/) version _2.7.0_ or greater.
 * [__RubyGems__](https://github.com/rubygems/rubygems) version _3.1.2_ or greater.  _RubyGems comes with the Ruby installation by default._
27
28
29

Most of the additional dependencies are managed using the [__Bundler__](https://github.com/bundler/bundler) gem.

Jesse Tilro's avatar
Jesse Tilro committed
30
For the linux continuous integration environment, the following system dependencies are required:
31
32
33

* Chromedriver

Taico Aerts's avatar
Taico Aerts committed
34
The application is database-agnostic by design, and can thus be used in combination with different RDBMSes (e.g. PostgreSQL, MySQL or SQLite). For development environments, SQLite is configured as database type. For the production environment, MySQL is configured as database type.
35
36
37
38
39

## Learning
---

Before working on this project, it is recommended to invest some time in getting to know the many conventions and the workflow imposed by Ruby on Rails. An excellent source for this purpose are the official [__Ruby on Rails Guides__](http://guides.rubyonrails.org/).
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

## Tooling
---

### Setup

After cloning the project, navigate to the project directory and run the following command:

`bin/setup`

### Starting a server

To run the project locally in a development environment, navigate to the project directory and run:

`bin/rails s`

### Testing

To run the automated test suites, navigate to the project directory and run:

`bin/rake`
or
`bin/rake test`
or
`bin/rails test`
or
`bin/rails t`

Jesse Tilro's avatar
Jesse Tilro committed
68
69
70
71
72
73
#### System Testing

To run the system tests - tests that use browser automation techniques to test at acceptance level - run the following command:

`bin/rails test:system`

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
#### Test Coverage

The [__SimpleCov__](https://github.com/colszowka/simplecov) gem (managed by Bundler) was configured to generate test coverage reports. After running the tests, an (updated) HTML site reporting on test coverage can be found in the _coverage_ subdirectory. (On the Jenkins CI server, the report is stored centrally and can be inspected via the Jenkins web interface.)

#### Static Analysis

For static analysis, the [__Rubocop__](https://github.com/bbatsov/rubocop) gem was configured. To run the analysis, enter the following command:

`rubocop`

This process can be [integrated with various development tools](https://rubocop.readthedocs.io/en/latest/integration_with_other_tools/). Since the development team used the [__Atom__](https://atom.io/) text editor, instructions will follow on how to integrate Rubocop with Atom.

`apm install linter`

`apm install linter-rubocop`

When Atom prompts whether it should install a certain dependency, answer 'Yes'. Restart Atom and you are good to go.

#### Security Testing

Jesse Tilro's avatar
Jesse Tilro committed
94
95
96
To test the system for security vulnerabilities, run:

`brakeman`
97

Jesse Tilro's avatar
Jesse Tilro committed
98
To check the dependencies of the system for vulnerabilities, run:
99

Jesse Tilro's avatar
Jesse Tilro committed
100
101
102
```
bundle-audit update
bundle-audit
Taico Aerts's avatar
Taico Aerts committed
103
104
```

Taico Aerts's avatar
Taico Aerts committed
105
106
107
108
109
## Connecting SAML
---

SAML can be connected by setting the profile in /config/initializers/devise.rb . The certificate files are stored in /certificates/<profile_name>/ and are `certificate`, `idp_cert` and `private_key`.

Taico Aerts's avatar
Taico Aerts committed
110
111
112
113
114
115
116
117
## Resolving Issues
---

### Setup
#### Libraries
At least the following libraries need to be installed in order to sucessfully complete the setup:


118
119
120
121
122
| apt                 | yum                 | brew                                                                                                |
|---------------------|---------------------|-----------------------------------------------------------------------------------------------------|
| libsqlite3-dev      | sqlite-devel        | sqlite3                                                                                             |
| libmysqlclient-dev  | mariadb-devel       | mysql-client (see [here](https://stackoverflow.com/questions/1857861/libmysqlclient15-dev-on-macs)) |
| libglpk-dev         | glpk-devel          | glpk                                                                                                |
Taico Aerts's avatar
Taico Aerts committed
123
124

#### RGLPK
125
Installing rglpk can fail if you have an incompatible version of the libglpk library. It should work with libglpk v4.47 or newer, but it was tested only with libglpk v4.65. If you need a specific version, download libglpk from [http://ftp.gnu.org/gnu/glpk/](http://ftp.gnu.org/gnu/glpk/).
Taico Aerts's avatar
Taico Aerts committed
126
127
128
129
130
131

1. Download and extract
2. `./configure`
3. `make all`
4. `sudo make install`
5. `sudo ldconfig`
Taico Aerts's avatar
Taico Aerts committed
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177

## License
Project Forum
Copyright (C) 2022  EIP

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

This copyright and license applies to all of the source code files in the following folders, unless if indicated otherwise in a source code file:
* app/assets/images/tutorials
* app/channels
* app/controllers
* app/helpers
* app/jobs
* app/mailers
* app/models
* app/service
* app/validators
* app/views
* db
* lib
* manuals
* public (excluding images)
* test

The following folders carry both source files from the project (covered under the AGPLv3 license) as well as source files from libraries, to which a different license may apply. Please review the notice in each file carefully. If no notice is present, the source code file falls under the copyright and license of Project Forum (see above):
* app/assets/javascripts
* app/assets/stylesheets
* app/assets/config
* config

The following folders contain source code files from libraries, which is not covered by the license for Project Forum:
* bin
* vendor

If any doubt exists about the licensing of a particular source file, or if you otherwise would like more information on setting up or using Project Forum for your own institution, please contact EIP with the contact information listed on our website, https://eip.ewi.tudelft.nl.