Heads up: EduSchedule isn't actively maintained any longer, aside from occasional dependency updates in requirements.txt
.
a simple and modern web app that helps students and teachers manage appointments efficiently
Follow these instructions to set up a copy of the project for testing and development.
- If Python is not installed, go ahead and download and install the latest version of Python. This application is written and tested in Python 3.6. Ensure that
pip
andvirtualenv
are working as well; they will be used to install dependencies. On Ubuntu, install these by running
sudo apt install python3 python3-pip python3-virtualenv python python-pip python-virtualenv
And check if pip
is working by running
pip -V
- Install git. It can be installed from the repositories for nearly all Linux distros, but downloads are also available at https://git-scm.com/downloads. On Ubuntu, run
sudo apt install git
These instructions assume the use of a Linux system and a bash shell.
- Clone this repository:
git clone https://github.com/michaelpolinski/EduSchedule
cd EduSchedule
Note: to get up and running quickly, skip steps 2-5 below and simply run
bash configure.sh
Or, to do manual configuration, follow the remaining steps.
- Create a new virtual environment. This step is optional but highly recommended. Make a python3 virtual environment and activate it:
virtualenv -p python3 venv
source venv/bin/activate
- Install the project's dependencies:
cd scheduleApp
pip install -r requirements.txt
EduSchedule is built using Django.
- Make a copy of the
local_settings.py
file:
cd scheduleApp
cp local_settings.py.debug.example local_settings.py
Now, execute the make_key Python script:
python make_key.py
This will generate a random secret key used by various Django security features and place it into the newly-created local_settings.py
file; keep this file secret and don't copy it to other machines - especially in production.
- Run the database migrations:
cd ..
python manage.py migrate
- Run the server for local testing (runs on localhost:8000):
python manage.py runserver
Ensure that the virtual environment is activated when executing Django manage.py commands.
This section explains how to run EduSchedule on your own server.
Running EduSchedule in production requires a publicly-accessible server that has the ability to run Django, has access to a production database, and can send email. It is highly recommended to run EduSchedule on a Linux server or VPS where root shell access (or SSH access) is permitted.
A typical configuration would include the following software:
- NGINX (web server, to handle web traffic from clients and serve static files)
- Certbot (Let's Encrypt certificate tool, to obtain and deploy HTTPS certificates on the web server)
- Gunicorn (application server for Django, to run EduSchedule itself)
- Supervisor (process manager, to restart Gunicorn if it crashes and keep logs)
- Postfix (mail server, configured to send email from EduSchedule to users)
- Postgres (database server, to store all the EduSchedule data)
- EduSchedule and its dependencies (like Django), installed with
pip
Before configuring EduSchedule, the other software must be configured.
These configuration guides are currently very general and lack precise instructions. Help in expanding them would be greatly appreciated!
To install all the software components mentioned above, this one-liner will do the job on Ubuntu:
sudo apt install nginx-full gunicorn supervisor postfix postgresql-contrib certbot python-certbot-nginx
- NGINX should be configured to serve HTTP and HTTPS requests on a domain configured for use with the server. Ensure DNS records (specifically A, AAAA, and MX records) point to the server's IP address.
- Add the domain to the list of
ALLOWED_HOSTS
inlocal_settings.py
. - Redirect HTTP to HTTPS, and use appropriate security configurations (TLS 1.2 or higher, modern ciphers, and preferably HSTS, which can be preloaded). See the Mozilla article on server-side TLS and the Mozilla SSL Configuration Generator, which can help a lot with the security aspect of setting up NGINX.
- Obtain HTTPS certificates for your domain using Certbot (use
certbot certonly
), and add them to the NGINX configuration accordingly. Installing the NGINX plugin for Certbot is preferred, as the certificates can then be renewed without needing to restart NGINX. - Configure NGINX to serve static files on
https://[example.com]/static/
and pass other requests to Gunicorn, the application server that runs Django. The static files directory is, by default, inEduSchedule/scheduleApp/scheduleApp/staticfiles/
(this can be changed inlocal_settings.py
).
- Create a bash script that will start Gunicorn. This script should activate the
virtualenv
(see Getting Started above), set the environment variables DJANGO_SETTINGS_MODULE and PYTHONPATH, and startgunicorn
. Don't forget to make it executable withchmod +x
. - See the Gunicorn deployment docs for instructions and for help on configuring Gunicorn to work with NGINX.
- Create a Supervisor configuration file in
/etc/supervisor/conf.d/
withautostart=true
that will run the bash script that was created to start Gunicorn.
- Create a new database user and a new database, giving the user a strong password.
- Copy the database name, username, and password to the
local_settings.py
file in the appropriate place so that Django can communicate with the database. - Be sure to restrict access to the database using a firewall like
ufw
(comes with Ubuntu) to prevent breaches.
- Configure Postfix as a send-only mail server. The same certificates used for encrypting HTTPS traffic should be used for Postfix to encrypt emails going to users.
- The Postfix documentation can be cryptic. This article is a very helpful resource for configuring your email server.
- Be sure to restrict access to email server using a firewall like
ufw
(comes with Ubuntu) to prevent abuse of the mail server. - Configure the DEFAULT_FROM_EMAIL in
local_settings.py
so that emails sent to users come from a reasonable address, like no-reply@example.com.
- Follow the "Getting Started" instructions above. Instead of using
local_settings.py.debug.example
as a template, uselocal_settings.py.example
and configure it to integrate with the rest of the software now running on your production server. - Instead of running the server with
python manage.py runserver
, usesupervisorctl
to start and stop the server.