Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README updated #36

Merged
merged 9 commits into from
Oct 11, 2024
Merged

README updated #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
18e6adb
README file updated
sammy-sandhu Sep 12, 2024
8a069a1
Edited configurations in README
sammy-sandhu Sep 12, 2024
d833882
README fixed
sammy-sandhu Sep 12, 2024
c422d40
README - added line spacing
sammy-sandhu Sep 12, 2024
191686c
docker compose command fixed
sammy-sandhu Sep 12, 2024
6ae1ab4
Adding license to README
sammy-sandhu Sep 12, 2024
3365378
README - fixed bullet numbering
sammy-sandhu Sep 12, 2024
7582e03
add collectstatic
KarenAJ Sep 18, 2024
9511e22
Update start-app.sh
KarenAJ Sep 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/cd-workflow.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ jobs:
docker network create openlxp
echo "Docker network successfully created"
echo "Running coverage unit test"
docker-compose --env-file ./.env run app sh -c "python manage.py waitdb && coverage run manage.py test --tag=unit && coverage report && coverage report --fail-under=80"
docker compose --env-file ./.env run app sh -c "python manage.py waitdb && coverage run manage.py test --tag=unit && coverage report && coverage report --fail-under=80"

# sonarcloud:
# name: SonarCloud
Expand Down
221 changes: 106 additions & 115 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,135 +1,122 @@
# Enterprise Course Catalog: OPENLXP-XMS
# Enterprise Course Catalog: OpenLXP-XMS
The Experience Management Service (XMS) is a part of the OpenLXP Enterprise Course Catalog (ECC) platform. It is the backend responsible for managing courses/catalogs.

XMS is the user interface facilitating modification and augmentation of records by learning experience owners and managers.

# Prerequisites
`Python >=3.7` : Download and install python from here [Python](https://www.python.org/downloads/).
This Django web application enables experience owners/managers to modify/augment experience metadata via (i.e., the "admin portal") REST API. It utilizes the Django admin UI for system configuration and management.

`Docker` : Download and install Docker from here [Docker](https://www.docker.com/products/docker-desktop).
## Prerequisites
### Install Docker & docker-compose
#### Windows & MacOS
- Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop) (docker compose included)

`XML Security Headers` : Download and install XML Security Headers for your operating system (`libxml2-dev` and `libxmlsec1-dev` in some linux distros).

#### Linux
You can download Docker Compose binaries from the
[release page](https://github.com/docker/compose/releases) on this repository.

## Environment Variables
Rename the relevant binary for your OS to `docker-compose` and copy it to `$HOME/.docker/cli-plugins`

The list of required variables is below
Or copy it into one of these folders to install it system-wide:

`DB_NAME` - The name to give the database
* `/usr/local/lib/docker/cli-plugins` OR `/usr/local/libexec/docker/cli-plugins`
* `/usr/lib/docker/cli-plugins` OR `/usr/libexec/docker/cli-plugins`

`DB_USER` - The name of the user to use when connecting to the database.
When testing use root to allow the creation of a test database
(might require making the downloaded file executable with `chmod +x`)

`DB_PASSWORD` - The password for the user to access the database
### Python
`Python >=3.9` : Download and install it from here [Python](https://www.python.org/downloads/).

`DB_ROOT_PASSWORD` - The password for the root user to access the database, should be the same as `DB_PASSWORD` if using the root user

`DB_HOST` - The host name, IP, or docker container name of the database

`DJANGO_SUPERUSER_USERNAME` - The username of the superuser that will be created in the application

`DJANGO_SUPERUSER_PASSWORD` - The password of the superuser that will be created in the application

`DJANGO_SUPERUSER_EMAIL` - The email of the superuser that will be created in the application

`AWS_ACCESS_KEY_ID` - The Access Key ID for AWS

`AWS_SECRET_ACCESS_KEY` - The Secret Access Key for AWS

`AWS_DEFAULT_REGION` - The region for AWS

`SECRET_KEY_VAL` - The Secret Key for Django

`LOG_PATH` - The path to the log file to use

`ENTITY_ID` - The Entity ID used to identify this application to Identity Providers when using Single Sign On

`SP_PUBLIC_CERT` - The Public Key to use when this application communicates with Identity Providers to use Single Sign On

`SP_PRIVATE_KEY` - The Private Key to use when this application communicates with Identity Providers to use Single Sign On

`CERT_VOLUME` - The path to the certificate (on the host machine) to use when connecting to AWS


# Installation

1. Clone the Github repository:

https://github.com/OpenLXP/openlxp-xms.git

2. Open terminal at the root directory of the project.

example: ~/PycharmProjects/openlxp-xms

3. Run command to install all the requirements from requirements.txt

docker-compose build.

4. Once the installation and build are done, run the below command to start the server.

docker-compose up

5. Once the server is up, go to the admin page:
## 1. Clone the project
Clone the Github repository
```
git clone https://github.com/OpenLXP/openlxp-xms.git
```

## 2. Set up your environment variables
- Create a `.env` file in the root directory
- The following environment variables are required:

| Environment Variable | Description |
| ------------------------- | ----------- |
| AWS_ACCESS_KEY_ID | The Access Key ID for AWS |
| AWS_SECRET_ACCESS_KEY | The Secret Access Key for AWS |
| AWS_DEFAULT_REGION | The region for AWS |
| CSRF_COOKIE_DOMAIN | The domain to be used when setting the CSRF cookie. This can be useful for easily allowing cross-subdomain requests to be excluded from the normal cross site request forgery protection. |
| CSRF_TRUSTED_ORIGINS | A list of trusted origins for unsafe requests |
| DB_HOST | The host name, IP, or docker container name of the database |
| DB_NAME | The name to give the database |
| DB_PASSWORD | The password for the user to access the database |
| DB_ROOT_PASSWORD | The password for the root user to access the database, should be the same as `DB_PASSWORD` if using the root user |
| DB_USER | The name of the user to use when connecting to the database. When testing use root to allow the creation of a test database |
| DJANGO_SUPERUSER_EMAIL | The email of the superuser that will be created in the application |
| DJANGO_SUPERUSER_PASSWORD | The password of the superuser that will be created in the application |
| DJANGO_SUPERUSER_USERNAME | The username of the superuser that will be created in the application |
| ENTITY_ID | The Entity ID used to identify this application to Identity Providers when using Single Sign On |
| LOG_PATH | The path to the log file to use |
| SECRET_KEY_VAL | The Secret Key for Django |
| SP_PRIVATE_KEY | The Private Key to use when this application communicates with Identity Providers to use Single Sign On |
| SP_PUBLIC_CERT | The Public Key to use when this application communicates with Identity Providers to use Single Sign On |


## 3. Deployment
1. Create the OpenLXP Docker network.
Open a terminal and run the following command in the root directory of the project.
```
docker network create openlxp
```

2. Run the docker compose command below to deploy XMS with its resources.
```
docker-compose up -d --build
```

## 4. Configuration for XMS
1. Navigate over to `http://localhost:8000/admin/` in your browser and login to the Django Admin page with the admin credentials set in your `.env` (`DJANGO_SUPERUSER_EMAIL` & `DJANGO_SUPERUSER_PASSWORD`)

2. <u>CONFIGURATIONS</u>
- Configure Experience Management Service (XMS)
1. Click on `Xms connections` > `Add Xms connection`
- Enter configurations below:

- `Target xis metadata api`: Metadata API Endpoint to connect to on an XIS instance.

- `XIS catalogs api`: Catalogs API Endpoint to connect to on an XIS instance.

3. <u>OPENLXP AUTHENTICATION</u>
- Configure Security Assertion Markup Language (SAML)
1. Click on `Saml configurations` > `Add saml configurations`
- Enter configurations below:

- `Name`: The name that will be used to identify the IdP in the URL.

- `Entity id`: The unique name provided by the IdP.

- `Url`: The connection URL to connect to the IdP at.

- `Cert`: The public cert used to connect to the IdP.

- `Attribute mapping`: The JSON formatted mapping to convert attributes provided by the IdP, to a User in this system.

## 5. Removing Deployment
To destroy the created resources, simply run the docker-compose command below in your terminal:

http://localhost:8000/admin (replace localhost with server IP)


# Configuration

1. On the Admin page, log in with the admin credentials


2. `Add xms configuration`: Configure Experience Management Service (XMS):

`Target xis metadata api`: Metadata API Endpoint to connect to on an XIS instance.

`XIS catalogs api`: Catalogs API Endpoint to connect to on an XIS instance.


3. `Add Saml configuration`: Configure Security Assertion Markup Language (SAML):

`Name`: The name that will be used to identify the IdP in the URL.

`Entity id`: The unique name provided by the IdP.

`Url`: The connection URL to connect to the IdP at.

`Cert`: The public cert used to connect to the IdP.

`Attribute mapping`: The JSON formatted mapping to convert attributes provided by the IdP, to a User in this system.


4. `Add sender email configuration`: Configure the sender email address from which conformance alerts are sent.
docker-compose down

## Troubleshooting
- If the container builds but crashes, or error logs a bunch of unrecognized commands, the issue is usually incorrect line endings. Most IDEs/Text Editors allow changing the line endings, but the dos2unix utility can also be used to change the line endings of `start-app.sh` and `start-server.sh` to LF.

5. `Add receiver email configuration` :
Add an email list to send conformance alerts. When the email gets added, an email verification email will get sent out. In addition, conformance alerts will get sent to only verified email IDs.

- A good basic troubleshooting step is to use `docker-compose down` and then `docker-compose up --build` to rebuild the app image; however, this will delete everything in the database.

# Troubleshooting
- XMLSEC
- If the build fails when pip tries to install xmlsec, the issue is usually missing libraries.

A good basic troubleshooting step is to use `docker-compose down` and then `docker-compose up --build` to rebuild the app image; however, this will delete everything in the database.
- The xmlsec package includes instructions for installing the libraries on common platforms in the [documentation](https://github.com/mehcode/python-xmlsec/blob/master/README.rst#install)

## XMLSEC

If the build fails when pip tries to install xmlsec, the issue is usually missing libraries.

The xmlsec package includes instructions for installing the libraries on common platforms in the [documentation](https://github.com/mehcode/python-xmlsec/blob/master/README.rst#install)

## Line Endings

If the container builds but crashes or logs an error of unrecognized commands, the issue is usually incorrect line endings.

Most IDEs/Text Editors allow changing the line endings, but the dos2unix utility can also be used to change the line endings of `start-app.sh` and `start-server.sh` to LF.


# Update

To update an existing installation:

1. Pull the latest changes using git

2. Restart the application using `docker-compose restart`

# Testing
## Testing

To run the automated tests on the application run the command below

Expand All @@ -139,14 +126,18 @@ Test coverage information will be stored in an htmlcov directory
docker-compose --env-file .env run app sh -c "coverage run manage.py test && coverage html && flake8"
```

# Authentication
## Authentication

The environment variables `SP_PUBLIC_CERT`, `SP_PRIVATE_KEY` , and `SP_ENTITY_ID` must be defined (if using docker-compose the variables can be passed through).

Information on the settings for the authentication module can be found on the [OpenLXP-Authentication repo](https://github.com/OpenLXP/openlxp-authentication).


# Authorization
## Authorization

The setting `OPEN_ENDPOINTS` can be defined in the django settings file.
It is a list of strings (regex notation may be used) for URLs that should not check for authentication or authorization.
It is a list of strings (regex notation may be used) for URLs that should not check for authentication or authorization.

## License

This project uses the [MIT](http://www.apache.org/licenses/LICENSE-2.0) license.
4 changes: 3 additions & 1 deletion start-app.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

python manage.py waitdb
python manage.py migrate
python manage.py createcachetable
python manage.py collectstatic --no-input
python manage.py loaddata admin_theme_data.json
cd /opt/app/
pwd
./start-server.sh
./start-server.sh
Loading