Skip to content

Commit a0499c8

Browse files
adi-herwana-nusadi-herwana-nus
adi-herwana-nus
authored and
adi-herwana-nus
committed
docs: readme update; update local setup to init correctly
1 parent c14d257 commit a0499c8

File tree

5 files changed

+121
-90
lines changed

5 files changed

+121
-90
lines changed

‎README.md

+17-88
Original file line numberDiff line numberDiff line change
@@ -15,107 +15,36 @@ Coursemology is an open source gamified learning platform that enables educators
1515

1616
### System Requirements
1717

18-
1. Ruby (= 3.3.5)
19-
2. Ruby on Rails (= 7.2.1)
20-
3. PostgreSQL (>= 9.5)
21-
4. ImageMagick or GraphicsMagick (For [MiniMagick](https://github.com/minimagick/minimagick) - if PDF processing doesn't work for the import of scribing questions, download Ghostscript)
22-
5. Node.js (v18 LTS)
23-
6. Yarn
24-
7. Installed docker
25-
8. Redis
26-
27-
Coursemology uses [Ruby on Rails](http://rubyonrails.org/). In addition, some front-end components use [React.js](https://facebook.github.io/react/). This [guide](https://gorails.com/setup/) written by the awesome people at GoRails should help you to get started on Ruby on Rails (however, be careful about the Rails version that you are going to install here. Please refer to the system requirements for the version of Rails you need to have for your system)
18+
1. **Ruby** (= 3.3.5)
19+
2. **Ruby on Rails** (= 7.2.2.1)
20+
3. **PostgreSQL** (= 16) with **PGVector extension**
21+
4. **ImageMagick** or **GraphicsMagick** (For [MiniMagick](https://github.com/minimagick/minimagick) - if PDF processing doesn't work for the import of scribing questions, download **Ghostscript**)
22+
5. **Node.js** (v22 LTS)
23+
6. **Yarn**
24+
7. **Docker** (installed and running)
25+
8. **Redis**
2826

2927
### Getting Started
3028

31-
1. We use submodules in the git repo; use this command to update submodules:
29+
We use Git submodules. Run the following command to initialize them before proceeding:
3230

3331
```sh
3432
$ git submodule update --init --recursive
3533
```
3634

37-
2. Download bundler to install dependencies
38-
39-
```sh
40-
$ gem install bundler:2.5.9
41-
```
42-
43-
3. Install ruby dependencies
44-
45-
```sh
46-
$ bundle config set --local without 'ci:production'
47-
$ bundle install
48-
```
49-
50-
4. Install javascript dependencies
51-
52-
```sh
53-
$ cd client && yarn; cd -
54-
```
55-
56-
5. Create and seed the database
57-
58-
```sh
59-
$ bundle exec rake db:setup
60-
```
61-
62-
6. We are using [Keycloak](https://www.keycloak.org/) as our Identity and Access Management (IAM) solution. Before proceeding to the next step, please navigate to `./authentication` folder, follow the instruction provided over the [README](https://github.com/Coursemology/coursemology2/blob/master/authentication/README.md), and then ensure that the Docker for Coursemology Authentication is running and that you are able to access the Keycloak site as mentioned in the very last step of that instruction
63-
64-
7. Initialize .env files for Frontend and Backend
65-
66-
```sh
67-
$ cp env .env; cp client/env client/.env
68-
```
69-
70-
You may need to add specific API keys (such as the [GOOGLE_RECAPTCHA_SITE_KEY](https://developers.google.com/recaptcha/docs/faq#id-like-to-run-automated-tests-with-recaptcha.-what-should-i-do)) to the .env files for testing specific features.
71-
72-
8. Open up 3 different terminals. On the terminal for Frontend in the `client` directory, run
73-
74-
```
75-
yarn build:development
76-
```
77-
78-
on the terminal for authentication service in the `authentication` directory, if you have not yet started Keycloak, run
79-
80-
```
81-
docker compose up
82-
```
83-
84-
or
85-
86-
```
87-
docker-compose up
88-
```
89-
90-
and on the terminal for Backend, run
91-
92-
```
93-
bundle exec rails s -p 3000
94-
```
95-
96-
9. Access the App by visiting `http://localhost:8080`
97-
98-
10. You're all set! Simply login with the default username and password:
99-
100-
> Email: `[email protected]`
101-
>
102-
> Password: `Coursemology!`
103-
104-
### Configuration
105-
106-
#### Multi Tenancy
35+
Coursemology consists of three main components:
36+
1. [Keycloak authentication provider](./authentication/README.md)
37+
2. [Ruby on Rails application server](./app/README.md)
38+
3. [React frontend client](./client/README.md)
10739

108-
To make sure that multi tenancy works correctly for you, change the default host in `config/application.rb` before deploying:
40+
Set up and run each component sequentially by following the linked documentation pages. As you proceed, open a new terminal window for each component after the previous component has been fully set up and started running.
10941

110-
```ruby
111-
config.x.default_host = 'your_domain.com'
112-
```
42+
Once each component has been set up and is running on their own terminals, you can access the app by visiting [http://localhost:8080](http://localhost:8080), and log in using the default user email and password:
11343

114-
#### Opening Reminder Emails
44+
email: `[email protected]`
45+
password: `Coursemology!`
11546

116-
Email reminders for items which are about to start are sent via a cronjob which should be run once an hour. See `config/initializers/sidekiq.rb` and `config/schedule.yml` for sample configuration which assumes that the [Sidekiq](https://github.com/mperham/sidekiq) and [Sidekiq-Cron](https://github.com/ondrejbartas/sidekiq-cron) gems are used.
11747

118-
If you use a different job scheduler, edit those files so your favourite job scheduler invokes the `ConsolidatedItemEmailJob` job once an hour.
11948

12049
## Found Boogs?
12150

‎app/README.md

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Coursemology App Server
2+
3+
Coursemology uses [Ruby on Rails](http://rubyonrails.org/) as its backend app server. This [guide](https://gorails.com/setup/) written by the awesome people at GoRails should help you to get started on Ruby on Rails (however, be careful about the Rails version you are going to install here, and make sure your system meets its requirements).
4+
5+
## Getting Started
6+
7+
These commands should be run with the repository root directory (one level up from where this README file is) as the working directory.
8+
9+
1. Download bundler to install dependencies
10+
11+
```sh
12+
gem install bundler:2.5.9
13+
```
14+
15+
2. Install ruby dependencies
16+
17+
```sh
18+
bundle config set --local without 'ci:production'
19+
bundle install
20+
```
21+
22+
3. Create and seed the database
23+
24+
```sh
25+
bundle exec rake db:setup
26+
```
27+
28+
4. Initialize .env file
29+
30+
```sh
31+
cp env .env
32+
```
33+
34+
You may need to add specific API keys (such as the [GOOGLE_RECAPTCHA_SITE_KEY](https://developers.google.com/recaptcha/docs/faq#id-like-to-run-automated-tests-with-recaptcha.-what-should-i-do)) to the .env files for testing specific features.
35+
36+
5. To start the app server, run
37+
38+
```
39+
bundle exec rails s -p 3000
40+
```
41+
42+
## Configuration
43+
44+
### Multi Tenancy
45+
46+
To make sure that multi tenancy works correctly for you, change the default host in `config/application.rb` before deploying:
47+
48+
```ruby
49+
config.x.default_host = 'your_domain.com'
50+
```
51+
52+
### Opening Reminder Emails
53+
54+
Email reminders for items which are about to start are sent via a cronjob which should be run once an hour. See [config/initializers/sidekiq.rb](../config/initializers/sidekiq.rb) and [config/schedule.yml](../config/schedule.yml) for sample configuration which assumes that the [Sidekiq](https://github.com/mperham/sidekiq) and [Sidekiq-Cron](https://github.com/ondrejbartas/sidekiq-cron) gems are used.
55+
56+
If you use a different job scheduler, edit those files so your favourite job scheduler invokes the `ConsolidatedItemEmailJob` job once an hour.

‎authentication/README.md

+21-1
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
1-
# Coursemology ID Authentication
1+
# Coursemology Authentication Provider
22

33
We are now using [Keycloak](https://www.keycloak.org/) as our Identity and Access Management (IAM) solution.
44

55
## Installation Guide
66

7+
### Getting Started
8+
9+
These commands should be run with the working directory `coursemology2/authentication` (the same directory this README file is in)
10+
711
1. Make sure you have docker and also docker-compose installed.
12+
813
2. Run the following command
914

1015
```
@@ -39,6 +44,21 @@ We are now using [Keycloak](https://www.keycloak.org/) as our Identity and Acces
3944

4045
## Further Guide
4146

47+
The local setup requires the authentication provider container to connect to the postgres service running on the host machine. On Windows and Mac, this is already set up by Docker Desktop, which lets the container do this by accessing the `host.docker.internal` hostname. On Linux devices, this can be set up by either:
48+
- installing [Docker Desktop for Linux](https://docs.docker.com/desktop/setup/install/linux/); **or**
49+
- changing the `KC_NETWORK_MODE` environment variable to `host`, and adding the following to the docker-compose service declaration:
50+
51+
```yaml
52+
53+
services:
54+
coursemology_auth:
55+
container_name: coursemology_authentication
56+
...
57+
extra_hosts:
58+
- 'host.docker.internal:127.0.0.1'
59+
60+
```
61+
4262
To ensure the smoothness in signing-in to Coursemology, you must ensure that the configuration for `KEYCLOAK_BE_CLIENT_SECRET` inside `.env` matches with the settings inside Keycloak. To do so, you can simply do the following instructions:
4363

4464
1. Sign-in to authentication pages by inputting the following credentials:

‎authentication/import/coursemology_realm.json

100644100755
+1-1
Original file line numberDiff line numberDiff line change
@@ -508,7 +508,7 @@
508508
"http://kranjisec.localhost:8080/*",
509509
"http://hwachong.localhost:8080/*",
510510
"http://sourceacademy.space/*",
511-
"http://localhost/*",
511+
"http://localhost:8080/*",
512512
"http://commonwealthsec.localhost:8080/*",
513513
"http://serangoongardensec.localhost:8080/*",
514514
"http://woodgrovesec.localhost:8080/*",

‎client/README.md

+26
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,31 @@
11
# Coursemology Client
22

3+
The front-end UI of Coursemology is written using [React.js](https://facebook.github.io/react/). Most of our pages and their components are written in TypeScript as [React functional components](https://react.dev/learn/your-first-component#defining-a-component), though there are some older parts in JS or using class components that should be migrated to functional components in the future.
4+
5+
## Getting Started
6+
7+
These commands should be run with the working directory `coursemology2/client` (the same directory this README file is in)
8+
9+
1. Install javascript dependencies
10+
11+
```sh
12+
yarn
13+
```
14+
15+
2. Run the following command to initialize `.env` files over here
16+
17+
```sh
18+
cp env .env
19+
```
20+
21+
You may need to add specific API keys (such as the [GOOGLE_RECAPTCHA_SITE_KEY](https://developers.google.com/recaptcha/docs/faq#id-like-to-run-automated-tests-with-recaptcha.-what-should-i-do)) to the .env files for testing specific features.
22+
23+
3. To start the frontend, run
24+
25+
```sh
26+
yarn build:development
27+
```
28+
329
## Translations
430

531
To generate a list of strings that need to be translated,

0 commit comments

Comments
 (0)