This project contains a minimal Django 4.2 site template for building SODAR Core based projects.
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.1.
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.
- Ubuntu 20.04 Xenial (Recommended for development)
- Python 3.9, 3.10 or 3.11
- Postgres 12+ (v16 recommended)
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
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:[email protected]/your_db
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.
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
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.
Once the installation is successful, you can continue to add your own SODAR based apps. See SODAR Core documentation. for further instructions.
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