This main branch of the repository contains the sources of EthicApp 2: A CSCL script engine developed in JavaScript and Angular.JS, which supports case-based ethics education in Higher Ed environments. Please review the organization README document for a detailed description of this project and its goals.
- EthicApp 2
Please head to the CONTRIBUTING document and review our communication channels for the project. The build and run documentation is intended for Linux-based systems, for this project. Please consider having a machine with a Linux-based OS (or with a Linux-friendly console such as bash
).
In order to work in the project you should be familiar with the following:
Knowledge of Docker and PostgreSQL could be helpful, but not required
In order to run the project natively in your computer, the following software is required:
- Node.JS (with
npm
). - PostgreSQL 10.X.
docker-compose
(from Docker) and npm
(due some setup tasks needed prior Docker shared volume).
Run npm install
, needed for a few DevOps utilities needed for this project (e.g. linters). You can skip this step if you are not going to contribute.
Initialize the file with development credential values for the Node web app such as the database connection URI:
npm run init-passwords-js
mkdir secrets
echo 'qwerty-dev-token' > ./secrets/jwt_token
The virtualized Postgres server is configured to run with a mounted Docker volume. Setup this with:
npm run init-db
This will create a directory at $HOST_DB_VOLUME_PATH
(see the DotEnv file) in your filesystem, containing the preset development database, thus being preserved despite the state of the database container.
Finally, it is mandatory to build the "bundles" for static assets:
npm run build
Head into ethicapp
and run npm install
for installing all dependencies. Then, once your Postgres server is up and running with the appropriate data and configuration at passwords.js
(which is up to you), head into ethicapp
directory and run the following for starting the web server at the default port 8080
:
npm run start
Note: you can change the web server port by setting a custom PORT
variable for the command, e.g. PORT=11500 npm run start
.
This is the recommended (and most documented) way to run the environment.
docker-compose down --remove-orphans
docker-compose up --build --detach
After those commands are executed, the dockerized web server will be available at http://localhost:$NODE_PORT
, and PgAdmin will also start serving at http://localhost:$PGADMIN_PORT
(values declared at the DotEnv file).
Then, you can check the output of any desired service with:
docker-compose logs -f $SERVICE_NAME
For checking which users are available to log-in as in the Node web application, please check this file.
Note: if you experience any issue while attempting to log-in as any of those users, please run npm run clear-sessions
(at the root project directory) for preventing previous sessions conflicting with the current runtime.
Please refer to the INSTALL Markdown for a detail information on how to run the app on production mode.
The root package.json
file contains some useful scripts for initialization and/or debugging, which are detailed at the following table (ordered by relevance) and can be easily run with npm run $Script
.
Script | Description |
---|---|
init-passwords-js |
For section 3.2. |
init-db |
For section 3.4. |
lint-$LANG |
For running a lint check for a given LANG . Values can be js , html , css or sql . |
fix-$LANG |
Runs automatic formatting fixes for linting rules, given a LANG . Values can be js , css or sql . |
clear-sessions |
Deletes all web sessions (from local filesystem). Needed when authentication or other features gets buggy in certain cases. See issue #151. It does need superuser permissions, somehow. |
psql |
Quickly run a command-line Postgres client to the containerized development database. |
pgdump and pgrestore |
Easily dumping/restoring the containerized database, if desired. |
build-js |
Builds asset bundle for static frontend JS files. |
build-css |
Builds asset bundle for static frontend CSS files. |
build-assets |
Runs build-js and build-css simultaneously. |
bundle-teacher-module |
Build and minifies controllers for faster file loading time |
build |
Runs build-js and build-css and bundle-teacher-module simultaneously. |
|
If you inspect the docker-compose
file, you will note that the database (and PgAdmin) use the unless-stopped
restart policy. This means that those services will keep running unless docker-compose down
is executed. Therefore, it is recommended to, when running the environment for the first time, first starting those services in detached mode:
docker-compose up --build --detach postgres pgadmin
Then, you can launch the Node service with, for instance:
docker-compose up --build node
By that way, Postgres and PgAdmin will run [constantly] on the background, they will be preserved even if the host machine is restarted, i.e., the developer will not have to re-enter the Postgres connection password whenever they want to connect to the database at PgAdmin.
If you have chosen not to use a Linux-based OS in your developing machine, read this section. If you are unfamiliar with Linux OSes, your first task would be install it on your machine (you may want to research about how to make a dual boot). If not, be aware that successful execution, debugging and updated runtime documentation will not be guaranteed, as the project is defined from its start to be executed and developed in a Linux environment.
You may have trouble running npm
scripts from appendix 5.1, including mandatory initialization tasks. If this happens, you will need to prepend bash -eu
to the commands at sections 3.2 and 3.4.
For Windows, you must have WSL, so that you can run a bash
(or alike) shell directly in your host filesystem. You also need to install npm
and docker-compose
inside that WSL console. Then, it is important that you work on the Linux-exclusive filesystem, due to permission troubles with Windows files (i.e. do not use any child directory of your default "C:
" Windows disk: /mnt/c
). For instance, clone the project at $HOME/ethicapp-main
and follow the instructions of the README file for building and running the environment properly. You also have to manage to open your IDE from the WSL bash
console (i.e. with code <CLONED_REPO_PATH>
).