Collab Coursebook

Description

Collab Coursebook is a platform for collaborative learning und knowledge organization. It provides a place to share and re-use notes and other learning materials.

Setup

This repository contains a Django project with several apps.

Requirements

Collab Coursebook has two types of requirements: System requirements are dependent on operating system and need to be installed manually beforehand. Python requirements will be installed inside a virtual environment (strongly recommended) during a setup.

System Requirements

• Python 3.8+ incl. development tools
• Virtualenv
• poppler
• TeX Distribution (e.g. TeX Live)
• wkhtmltopdf (used for exporting Markdown as PDF)
• For production using uwsgi:
  • C compiler e.g. gcc
  • uwsgi
  • uwsgi Python3 plugin
• For production using Apache (in addition to uwsgi)
  • the mod proxy uwsgi plugin for apache2

Python Requirements

Python requirements are listed in requirements.txt. They can be installed with pip using -r requirements.txt.

Distributable Setup

• In order to use Nestable2 correctly the dist folder is needed. This folder can be found here: https://github.com/RamonSmit/Nestable2
  • The folder must be placed in frontend/static/vendor/Nestable2.

Development Setup

• Create a new directory that should contain the files in the future, e.g. mkdir collab-coursebook
• Change into that directory cd collab-coursebook
• Clone this repository git clone URL .

Docker

For development there is a docker container. It contains only the runtime environment and is not indented for deployment usage! Build the image (may take some time, downloads complete TeXLive >4GB):

docker build -t collab .

Aterwards the container can be started with

docker run --name collab -p 8000:8000 -v "$PWD:/home/collab/collab-coursebook" -u "$(id -u):$(id -g)" -e "DOCKER_USER=$USER" collab

To restart it (for example after it crashed or the host rebooted) run

docker start collab

In your browser, access http://127.0.0.1:8000/ and continue from there.

In case you want to attach your IDE to the container, all file operations will be executed as the outside user. So no ownership problems should happen. Please note that the container does support passwordless sudo!

Linux

Automatic Setup

1. Execute the setup bash script utils/setup.sh

Manual Setup

1. Set up a virtual environment using the proper python version virtualenv venv -p python3
2. Activate virtualenv source venv/bin/activate
3. Install python requirements pip install -r requirements.txt
4. Set up necessary database tables etc. python manage.py migrate
5. Setup initial revision for all registered models for versioningpython manage.py createinitialrevisions
6. Prepare static files (can be omitted for dev setups) python manage.py collectstatic
7. Compile translations python manage.py compilemessages
8. Create a privileged user, credentials are entered interactively on CLI python manage.py createsuperuser
9. Deactivate virtualenv deactivate
10. Create the file collab_coursebook/settings_secrets.py (copy from settings_secrets.py.sample) and fill in the YouTube API key

Development Server

To start the application for development use python manage.py runserver 0:8000 from the root directory. Do not use this for deployment!

In your browser, access http://127.0.0.1:8000/ and continue from there.

Windows

Manual Setup

1. Set up a virtual environment using the proper python version virtualenv venv -p python3
2. Activate virtualenv .\venv\Scripts\activate
3. Install python requirements pip install -r requirements.txt
4. Install python magic-bin pip install python-magic-bin
5. Set up necessary database tables etc. python manage.py migrate
6. Setup initial revision for all registered models for versioningpython manage.py createinitialrevisions
7. Prepare static files (can be omitted for dev setups) python manage.py collectstatic
8. Compile translations python manage.py compilemessages
9. Create a privileged user, credentials are entered interactively on CLI python manage.py createsuperuser
10. Deactivate virtualenv deactivate
11. Create the file collab_coursebook/settings_secrets.py (copy from settings_secrets.py.sample) and fill in the YouTube API key for development regarding YouTube Videos

Development Server

To start the application for development use python manage.py runserver 0.0.0.0:8000 from the root directory. Do not use this for deployment!

In your browser, access http://127.0.0.1:8000/ and continue from there.

PyLint

To be able to run PyLint, go into content/static/yt_api.py, comment out the import from secret settings and set yt_api_key = "". Otherwise PyLint will not run because it tries to import from a file that doesn't exist.

Deployment Setup

This application can be deployed using a web server as any other Django application. Remember to use a secret key that is not stored in any repository or similar, and disable DEBUG mode (settings.py).

Step-by-Step Instructions

1. Log into your system with a sudo user

2. Install system requirements

3. Create a folder, e.g. mkdir /srv/collab-coursebook/

4. Change to the new directory cd /srv/collab-coursebook/

5. Clone this repository git clone URL .

6. Set up a virtual environment using the proper python version virtualenv venv -p python3

7. Activate virtualenv source venv/bin/activate

8. Update tools pip install --upgrade setuptools pip wheel

9. Install python requirements pip install -r requirements.txt

10. Install further python requirements pip install psycopg2-binary uwsgi

11. Create postgres user and database and grant rights

    • sudo -u postgres createuser
    • sudo -u postgres createdb
    • sudo -u postgres psql
    • psql=# alter user with encrypted password '';
    • psql=# grant all privileges on database to ;

12. Create the file collab_coursebook/settings_secrets.py (copy from settings_secrets.py.sample) and fill it with the necessary secrets (e.g. generated by tr -dc 'a-z0-9!@#$%^&*(-_=+)' < /dev/urandom | head -c50) (it is a good idea to restrict read permissions from others)

13. If necessary enable uwsgi proxy plugin for Apache e.g.a2enmod proxy_uwsgi

14. Edit the apache config to serve the application and the static and media files, e.g. on a dedicated system in /etc/apache2/sites-enabled/000-default.conf within the VirtualHost tag add:

    Alias /static /srv/collab-coursebook/static
    <Directory /srv/collab-coursebook/static>
      Require all granted
    </Directory>
    
    Alias /media /srv/collab-coursebook/media
    <Directory /srv/collab-coursebook/media>
      Require all granted
    </Directory>
       
    ProxyPassMatch ^/media/ !
    ProxyPassMatch ^/static/ !
    ProxyPass / uwsgi://127.0.0.1:3035/
    

or create a new config (.conf) file (similar to apache-collab-coursebook.conf) replacing $SUBDOMAIN with the subdomain the system should be available under, and $MAILADDRESS with the e-mail address of your administrator and $PATHTO with the appropriate paths. Copy or symlink it to /etc/apache2/sites-available. Then activate it with a2ensite collab-coursebook.

1. Restart Apache sudo apachectl restart
2. Create a dedicated user, e.g. adduser django --disabled-login
3. Transfer ownership of the folder to the new user chown -R django:django /srv/collab-coursebook
4. Copy or symlink the uwsgi config in uwsgi-collab-coursebook.ini to /etc/uwsgi/apps-available/ and then symlink it to /etc/uwsgi/apps-enabled/ using e.g., ln -s /srv/collab-coursebook/uwsgi-collab-coursebook.ini /etc/uwsgi/apps-available/collab-coursebook.ini and ln -s /etc/uwsgi/apps-available/collab-coursebook.ini /etc/uwsgi/apps-enabled/collab-coursebook.ini
5. Test your uwsgi configuration file withuwsgi --ini collab-coursebook.ini
6. Restart uwsgi sudo systemctl restart uwsgi
7. Execute the update script ./utils/update.sh --prod
8. If not already active on that server, obtain an SSL certificate, e.g., through Let's Encrypt

Updates

To update the setup to the current version on the main branch of the repository use the update script utils/update.sh or utils/update.sh --prod in production.

Afterwards, you may check your setup by executing utils/check.sh or utils/check.sh --prod in production.

Structure

This repository contains a Django project called collab_coursebook. The functionality is encapsulated into Django apps:

1. base: This app contains the general Django models used to represent courses, contents, etc.
2. frontend: This app provides everything the users see when reading or editing the content. It also contains a landing page.
3. content: This app provides models, rendering- and export code for the different supported types of contents.
4. export: This app contains export functions for the custom content collections (coursebooks).

Developer Notes

• To regenerate translations use python manage.py makemessages -l de_DE --ignore venv
• To create a data backup use python manage.py dumpdata --indent=2 > db.json --traceback