Skip to content
Erik Smistad edited this page Apr 26, 2024 · 8 revisions

This guide is for Ubuntu Linux. To setup annotation web for deployment on a server use apache2 and mod_wsgi. Security is important when working with medical data on an online server, see the security checklist for annotation web here.

1. First install packages

sudo apt-get install python3-pip apache2 libapache2-mod-wsgi-py3

2. Then clone the repo on the server for instance to /var/www/

cd /var/www/
git clone https://github.com/smistad/annotationweb.git

3. Setup up virtual environment on the server

cd annotationweb
virtualenv -ppython3 environment
source environment/bin/activate

4. Install requirements

pip install --upgrade pip # Make sure pip is up to date first
pip install -r requirements.txt

5. Create a secret key and disable debug mode
Generate a secret key and add it to settings.py

python manage.py shell -c 'from django.core.management import utils; print(utils.get_random_secret_key())'

Edit the file annotationweb/settings.py. Uncomment and set the SECRET_KEY to the output of the python command above. Remember to keep this key secret. You may change it, even when the system is in use, but note that users may be logged out. See here for more info: https://medium.com/@bayraktar.eralp/changing-rotating-django-secret-key-without-logging-users-out-804a29d3ea65

Then, disable debug mode by setting debug = False.

6. Initialize database

./manage.py makemigrations
./manage.py migrate

7. Create super user

./manage.py createsuperuser

8. Collect static files

./manage.py collectstatic

9. Fix user permissions
Apache needs write access to the database. Apache runs on the user wwww-data thus give this user write access to the root folder and the database file db.sqlite3

cd ..
sudo chown :www-data annotationweb
sudo chmod g+w annotationweb
cd annotationweb
sudo chown www-data db.sqlite3
sudo chmod g+w db.sqlite3

10. Create an apache config

sudo nano /etc/apache2/sites-available/annotationweb.conf

The config without any encryption (NOT RECOMMENDED) may look something like this:

<VirtualHost *:80>
    ServerName awesome-webserver.com

    ServerAdmin you@domain.com
    DocumentRoot /var/www/annotationweb/

    Alias /static /var/www/annotationweb/static
    <Directory /var/www/annotationweb/static>
        Require all granted
    </Directory>

    <Directory /var/www/annotationweb/annotationweb>
        <Files wsgi.py>
            Require all granted
        </Files>
    </Directory>

    WSGIDaemonProcess example python-path=/var/www/annotationweb/:/var/www/annotationweb/environment/lib/python3.6/site-packages
    WSGIProcessGroup example
    WSGIScriptAlias / /var/www/annotationweb/annotationweb/wsgi.py

    ErrorLog ${APACHE_LOG_DIR}/annotationweb.error.log
    CustomLog ${APACHE_LOG_DIR}/annotationweb.access.log combined
</VirtualHost>

If you are not using HTTPS, you are essentially transferring everything, login password, ultrasound images, on the annotation webpage totally unecnrypted over the internet! To use HTTPS/SSL encryption you need an SSL certificate, you can buy one cheap from services like namecheap.com or free from Let's encrypt. Store the certificate, the key, and the CA certificate files on the server, e.g. in folder /var/www/annotationweb/ssl/. The config with SSL/HTTPS end-to-end-encryption will then look something like this:

# Redirect to secure site
<VirtualHost *:80>
    ServerName awesome-webserver.com
    ServerAdmin you@domain.com
    Redirect permanent / https://awesome-webserver.no
</VirtualHost>

<VirtualHost *:443>
    # Common stuff
    ServerName awesome-webserver.com
    ServerAdmin you@domain.com
    DocumentRoot /var/www/annotationweb/

    # SSL stuff
    SSLEngine on
    # Only allow strong encryption, and disable SSLv3 
    SSLCipherSuite HIGH:!aNULL:!MD5:!SSLv3
    SSLCertificateFile "/var/www/annotationweb/ssl/certificate.crt"
    SSLCertificateKeyFile "/var/www/annotationweb/ssl/certificate.key"
    SSLCACertificateFile "/var/www/annotationweb/ssl/certificate.ca.crt"

    Alias /static /var/www/annotationweb/static
    <Directory /var/www/annotationweb/static>
        Require all granted
    </Directory>

    <Directory /var/www/annotationweb/annotationweb>
        <Files wsgi.py>
            Require all granted
        </Files>
    </Directory>

    WSGIDaemonProcess example python-path=/var/www/annotationweb/:/var/www/annotationweb/environment/lib/python3.6/site-packages
    WSGIProcessGroup example
    WSGIScriptAlias / /var/www/annotationweb/annotationweb/wsgi.py

    ErrorLog ${APACHE_LOG_DIR}/annotationweb.error.log
    CustomLog ${APACHE_LOG_DIR}/annotationweb.access.log combined
</VirtualHost>

11. Enable website and have fun

sudo a2ensite annotationweb
sudo systemctl reload apache2

A usual cause of error on the apache2 server, when enabling the website, is a syntax error in the configuration file. In such situations, you can use the command line apache2ctl configtest to debug the file.

Updating

1. Back up your database Your database is stored entirely in the db.sqlite3 file. Copy this to a safe location. You may also want to keep a copy of the code as well, so you can copy the entire project folder.

2. Pull latest changes from git

git pull

3. Update database

./manage.py migrate

4. Run server and have fun

./manage.py runserver