Skip to content
Snippets Groups Projects
Commit ffdbe4fc authored by Piotr Gawron's avatar Piotr Gawron
Browse files

Merge branch 'update-readme' into 'master' 

Update readme

See merge request NCER-PD/scheduling-system!297
parents f7172e71 c8522f3a
No related branches found
No related tags found
1 merge request!297Update readme
Pipeline #37226 passed
Hide whitespace changes
Inline Side-by-side
Showing
with 87 additions and 164 deletions
readme.md
+ 87
− 164
View file @ ffdbe4fc
...@@ -11,216 +11,139 @@ If you'd like to try out the application without preparing the environment, you ...@@ -11,216 +11,139 @@ If you'd like to try out the application without preparing the environment, you
docker-compose build && docker-compose up docker-compose build && docker-compose up
# To add a new user, type in the new terminal: # To add a new user, type in the new terminal:
docker-compose exec web sh docker-compose exec web sh
python manage.py createsuperuser python manage.py superworker
``` ```
## Required software (on ubuntu's OS family): ## Required software (on ubuntu's OS family):
- `sudo apt-get install libpq-dev python-dev postgresql postgresql-contrib python virtualenv python-virtualenv gcc python-lxml libxml2-dev libcurl4-openssl-dev libcurl4-gnutls-dev libgnutls28-dev` - install required dependencies on ubuntu
```bash
## Postgres installation sudo apt-get install python3, virtualenv, libcurl4-gnutls-dev, libpng-dev, libfreetype6-dev, libpq-dev, gcc, g++, python3-dev, libgnutls28-dev, libjpeg-dev, libfreetype6-dev, git
- If you don't have postgres installed, complete step seven from [https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-django-with-postgres-nginx-and-gunicorn](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-django-with-postgres-nginx-and-gunicorn) (remember to save all the credentials, they will be necessary to run the application).
## Developer project installation
- `mkdir -p ~/dev/smash`
- `cd ~/dev/smash`
- `git clone ssh://git@git-r3lab-server.uni.lu:8022/NCER-PD/scheduling-system.git`
- `cd scheduling-system`
- `virtualenv env` to create new virtualenv (contains clean python working environment)
- `. env/bin/activate` (to start using virtualenv)
- `pip install -r requirements.txt` to install project's dependencies
- Create `local_settings.py` file in `(./scheduling-system)/smash/smash` directory by copying the template in `(./scheduling-system)/smash/smash/local_settings.template` and edit your local_setttings.py file to change your database connection data.
- Update migration db scrpit from file structure (`./scheduling-system/smash/manage.py makemigrations`)
- Create the database by applying migrations (`./scheduling-system/smash/manage.py migrate`)
- Create the first, administrative, user- (`./scheduling-system/smash/manage.py createsuperuser`)
## Development
- Remember, that before working you have to activate _virtualenv_, by: `devel@host ~/home/smash/scheduling-system $ . env/bin/activate`
- In order to run development server, run: `devel@host ~/home/smash/scheduling-system/smash $ ./manage.py runserver` and go to `127.0.0.1:8000` in browser
- For reference of HTML tempalte, see [https://almsaeedstudio.com/themes/AdminLTE/pages/widgets.html#](https://almsaeedstudio.com/themes/AdminLTE/pages/widgets.html#)
### Mac Developers
In case of problems with the openssl version installed on the system:
``` ```
export PYCURL_SSL_LIBRARY=openssl - install nodejs
pip install pycurl --global-option=build_ext --global-option="-I/usr/local/Cellar/openssl/1.0.2k/include" --global-option="-L/usr/local/Cellar/openssl/1.0.2k/lib" --upgrade ```bash
pip install psycopg2 --global-option=build_ext --global-option="-I/usr/local/Cellar/openssl/1.0.2k/include" --global-option="-L/usr/local/Cellar/openssl/1.0.2k/lib" --upgrade curl -sL https://deb.nodesource.com/setup_14.x | bash -
apt-get install nodejs
``` ```
## Production deployment
- git pull and other project installation should be performed in a dir where this django app should be installed, in this tutorial it's /var/www/scheduling-system/
- install nginx: `apt-get install nginx`
- create gunicorn service in systemd (http://docs.gunicorn.org/en/stable/deploy.html#systemd):
### /etc/systemd/system/gunicorn.service ## Developer project installation
- clone smasch:
```bash
git clone ssh://git@git-r3lab-server.uni.lu:8022/NCER-PD/scheduling-system.git
``` ```
[Unit]
Description=gunicorn daemon
Requires=gunicorn.socket
After=network.target
[Service]
PIDFile=/run/gunicorn/pid
User=www-data
Group=www-data
WorkingDirectory=/var/www/scheduling-system/smash
ExecStart=/var/www/scheduling-system/env/bin/gunicorn --pid /run/gunicorn/pid smash.wsgi --error-logfile /var/log/gunicorn.log --log-level DEBUG --capture-output --limit-request-line 8192 - setup virtualenv with clean python3 working environment and start using it. Important python3.6 or higher is required
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s TERM $MAINPID
PrivateTmp=true
[Install] ```bash
WantedBy=multi-user.target cd scheduling-system
virtualenv env -p python3
. env/bin/activate
``` ```
Don't forget to change ownership of `/run/gunicorn/` folder and `/var/log/gunicorn.log` file. - install smasch dependencies
```
chown -R www-data:www-data /run/gunicorn/
touch /var/log/gunicorn.log
chown www-data:www-data /var/log/gunicorn.log
```
### /etc/systemd/system/gunicorn.socket
```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
npm install
``` ```
[Unit]
Description=gunicorn socket
[Socket] - Create `local_settings.py` file in `smash/smash` directory by copying the template in `smash/smash/local_settings.template` and edit your local_setttings.py file to change your database connection data.
ListenStream=/run/gunicorn/socket
ListenStream=0.0.0.0:9000
ListenStream=[::]:8000
[Install]
WantedBy=sockets.target
```
- modify nginx configuration
### /etc/nginx/nginx.conf ### Database configuration
There are two databases supported: `sqlite3` or `postgresql`. You can configure database connection in `smash/smash/local_settings.py`.
``` - sqlite3 database configuration looks like:
user www-data;
worker_processes auto;
pid /run/nginx.pid;
events { ```python
worker_connections 768; DATABASES = {
# multi_accept on; 'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': 'db.sqlite3',
}
} }
http { ```
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
types_hash_max_size 2048;
include /etc/nginx/mime.types;
default_type application/octet-stream;
##
# SSL Settings
##
ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # Dropping SSLv3, ref: POODLE
ssl_prefer_server_ciphers on;
##
# Logging Settings
##
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log;
##
# Gzip Settings
##
gzip on;
gzip_disable "msie6";
include /etc/nginx/conf.d/*.conf; - postgresql database configuration looks like:
include /etc/nginx/sites-enabled/*;
```python
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'smaschdb',
'USER': 'smaschuser',
'PASSWORD': 'smaschpassword',
'HOST': 'localhost',
'PORT': '',
'TEST': {
'NAME': 'dbtest',
},
}
} }
``` ```
### /etc/nginx/sites-enabled/default After database connection is configured setup a database by applying migration scripts and create admin user
```bash
./manage.py migrate
./manage.py superworker -u admin -e test@test.lu -f John -l Doe
``` ```
upstream app_server {
# fail_timeout=0 means we always retry an upstream even if it failed
# to return a good HTTP response
# for UNIX domain socket setups
server unix:/run/gunicorn/socket fail_timeout=0;
# for a TCP configuration
# server 192.168.0.7:8000 fail_timeout=0;
}
server {
listen 80 default_server;
listen [::]:80 default_server;
listen 443 ssl;
## Development
Remember, that before working you have to activate _virtualenv_ (in project directory), by:
root /var/www/html; ```bash
. env/bin/activate
```
# Add index.php to the list if you are using PHP In order to run development server, run:
index index.html index.htm index.nginx-debian.html;
server_name prc.parkinson.lu; ```bash
cd smash
./manage.py runserver
```
and go to `127.0.0.1:8000` in browser
ssl_certificate /etc/nginx/ssl/nginx.crt; ### Mac Developers
ssl_certificate_key /etc/nginx/ssl/nginx.key;
In case of problems with the openssl version installed on the system:
#configuration for static and media files hosted by nginx ```
location /media/ { export PYCURL_SSL_LIBRARY=openssl
root /var/www/scheduling-system-files; pip install pycurl --global-option=build_ext --global-option="-I/usr/local/Cellar/openssl/1.0.2k/include" --global-option="-L/usr/local/Cellar/openssl/1.0.2k/lib" --upgrade
} pip install psycopg2 --global-option=build_ext --global-option="-I/usr/local/Cellar/openssl/1.0.2k/include" --global-option="-L/usr/local/Cellar/openssl/1.0.2k/lib" --upgrade
```
location /static/ { ## Production deployment
root /var/www/scheduling-system-files; Smasch can be deployed using debian package provided in lcsb repository:
}
```bash
echo "deb http://repo-r3lab.uni.lu/debian/ stable main" | tee /etc/apt/sources.list.d/repo-r3lab.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 0xcb185f4e31872412
apt-get update
apt-get install -y smasch
```
location / { After smasch is installed you can start/stop it using systemd:
# checks for static file, if not found proxy to app
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# enable this if and only if you use HTTPS
# proxy_set_header X-Forwarded-Proto https;
proxy_set_header Host $http_host;
# we don't want nginx trying to do something clever with
# redirects, we set the Host: header above already.
proxy_redirect off;
proxy_pass http://app_server;
}
} ```bash
service smasch start
service smasch stop
``` ```
- extract static files and make them available via nginx: `./manage.py collectstatic`
- you start application by starting gunicorn and nginx: `service gunicorn start`, `service nginx start`
## Cron jobs (weekly emails) Smasch service will be listening on port 8888 - go to http://localhost:8888/. By default smasch will use sqlite3 database.
If weekly emails are required then cron must be edited to fire periodically django function that send emails. Configuration of smasch (`local_settings.py`) is in `/etc/smasch/smasch.py`.
```
> crontab -e
SHELL=/bin/bash
*/30 * * * * source /var/www/scheduling-system/env/bin/activate && python /var/www/scheduling-system/smash/manage.py runcrons >> /var/log/django-cronjob.log 2>&1
```
## Operations ## Operations
### Disable two steps authentication for a specific user ### Disable two steps authentication for a specific user
``` ```bash
./manage.py two_factor_disable ${USERNAME} ./manage.py two_factor_disable ${USERNAME}
``` ```
...@@ -228,7 +151,7 @@ SHELL=/bin/bash ...@@ -228,7 +151,7 @@ SHELL=/bin/bash
to import public holidays run: to import public holidays run:
``` ```bash
./manage.py holidays ${YEARS} ./manage.py holidays ${YEARS}
``` ```
...@@ -236,6 +159,6 @@ where ${YEARS} should be a space separated list of years for which the holidays ...@@ -236,6 +159,6 @@ where ${YEARS} should be a space separated list of years for which the holidays
example: example:
``` ```bash
./manage.py holidays 2017 2018 2019 ./manage.py holidays 2017 2018 2019
``` ```
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment