SODAR Django Site

This project contains a minimal Django 4.2 site template for building SODAR Core based projects.

Introduction

The site is based on a site template created with cookiecutter-django.

Included in this project are the critical OS and Python requirements, pre-set Django settings, a pre-installed SODAR Core framework and some helper scripts. It is also readily compatible with Selenium UI testing, coverage checking and continuous integration for GitHub Actions and GitLab-CI.

The current version of this site is compatible with SODAR Core v1.0.2.

Installation for Development

For instructions and best practices in Django development, see Django 4.2 documentation and Two Scoops of Django.

For SODAR Core concepts and instructions, see SODAR Core documentation.

The examples here use venv and pip, but you may also use e.g. conda for virtual environments and installing packages.

Requirements

• Ubuntu 20.04 Xenial (Recommended for development)
• Python 3.9, 3.10 or 3.11
• Postgres 12+ (v16 recommended)

System Installation

First you need to install OS dependencies, PostgreSQL 11 and Python 3.8+.

$ sudo utility/install_os_dependencies.sh
$ sudo utility/install_python.sh
$ sudo utility/install_postgres.sh

Database Setup

Create a PostgreSQL user and a database for your application. Make sure to give the user the permission to create further PostgreSQL databases (used for testing).

You can either use the helper script in utility/setup_database.sh or use psql manually. Make sure to replace the example values below with your actual database name, user name and password.

$ sudo su - postgres
$ psql
$ CREATE DATABASE your_db;
$ CREATE USER your_user WITH PASSWORD 'your_password';
$ GRANT ALL PRIVILEGES ON DATABASE your_db to your_user;
$ ALTER USER your_user CREATEDB;
$ \q

You have to add the credentials in the environment variable DATABASE_URL. For development it is recommended to place this variable in an .env file and set DJANGO_READ_DOT_ENV_FILE=1 in your actual environment. See config/settings/base.py for more information.

DATABASE_URL=postgres://your_user:your_password@127.0.0.1/your_db

Project Setup

Clone the repository, setup and activate the virtual environment. Once in the environment, install Python requirements for the project:

$ git clone https://github.com/bihealth/sodar_django_site.git
$ cd sodar_django_site
$ python -m venv .venv
$ source .venv/bin/activate
$ utility/install_python_dependencies.sh

Hint: At this point, you most likely want to rename the project and the website directory from sodar_django_site into the name of the system you will be developing.

LDAP Setup (Optional)

If you will be using LDAP/AD auth on your site, make sure to also run:

$ sudo utility/install_ldap_dependencies.sh
$ pip install -r requirements/ldap.txt

Final Setup

Initialize the database (this will also synchronize django-plugins):

$ ./manage.py migrate

Create a Django superuser for the web site:

$ ./manage.py createsuperuser

Retrieve icons to use on the site and collect static files:

$ ./manage.py geticons
$ ./manage.py collectstatic

Now you should be able to run the server:

$ make serve

Navigate to http://127.0.0.1:8000/ and log in to see the results. The site should be up and running with the default SODAR Core layout.

Note that if you are utilizing Celery or the bgjobs app, you will also need to configure and run Celery in a separate process.

Developing your Site

Once the installation is successful, you can continue to add your own SODAR based apps. See SODAR Core documentation. for further instructions.

Updating This Repository

Below is a checklist for updating the SODAR Django Site repository for a new SODAR Core version, applicable to SODAR Core developers.

• Upgrade system dependencies (if changed)
• Upgrade Python dependencies (if changed)
• Update utility scripts (if changed)
• Update Django settings files (if changed)
• Update URL config (if changed)
• Any other SODAR Core version specific updates if applicable
• Reinstall versioneer (if versioneer has been upgraded)
• Update SODAR version in requirements
• Update version number in docs