Development Installation
Instructions on how to install a local development version of SODAR Core are detailed here. Ubuntu 20.04 LTS (Focal) is the supported OS at this time. Later Ubuntu versions and Centos 7 have also been proven to to work, but some system dependencies may vary for different OS versions or distributions.
Installation and development should be possible on most recent versions of Linux, Mac and Windows (WSL2 recommended). However, this may require extra work and your mileage may vary.
If you need to set up the accompanying example site in Docker, please see online for up-to-date Docker setup tutorials for Django related to your operating system of choice.
Note
These instructions are also valid for the sodar-django-site repository.
System Dependencies
To get started, install the OS dependencies, Python >=3.9 (3.11 recommended) and PostgreSQL >=12 (16 recommended).
$ sudo utility/install_os_dependencies.sh
$ sudo utility/install_python.sh
$ sudo utility/install_postgres.sh
Database Setup
Next you need to setup the database and postgres user. You’ll be prompted to enter a database name, a username and a password.
$ sudo utility/setup_database.sh
You have to set the database URL and credentials for Django in the environment
variable DATABASE_URL
. For development it is recommended to place
environment variables in file .env
located in your project root. To enable
loading the file in Django, set DJANGO_READ_DOT_ENV_FILE=1
in your
environment variables when running SODAR or any of its management commands.
See config/settings/base.py
for more information and the env.example
file for an example environment file.
Example of the database URL variable as set within an .env
file:
DATABASE_URL=postgres://your-db:your-db@127.0.0.1/your-db
Repository and Environment Setup
Clone the repository, setup and activate the virtual environment. Once within the repository and an active virtual environment, install Python requirements for the project. Example:
$ python3.x -m venv .venv
$ source .venv/bin/activate
$ utility/install_python_dependencies.sh
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 example site:
$ ./manage.py createsuperuser --skip-checks --username admin
Run the geticons
and collectstatic
commands to download and enable
Iconify icons:
$ ./manage.py geticons
$ ./manage.py collectstatic
You are now able to run the server:
$ make serve
To enable periodic tasks, you need to start a Celery worker in addition to the
Django server. This is done by running the make celery
command in a separate
terminal.
$ make celery
Note
SODAR Core itself currently uses Celery tasks only for remote project synchronization for target sites. If developing a source site, running this process is not necessary.
Optional Steps
For creating a group of example users for your development site, you can run the
createdevusers
management command. This creates the users “alice”, “bob”,
“carol”, “dan” and “erin”. The users will be created with the password
“sodarpass”, unless a custom password is supplied via the -p
or
--password
argument.
$ ./manage.py createdevusers
Note
Having multiple non-admin user accounts is useful for developing and trying out project and member access management features. It is recommended to log in to a dev server as a regular user whenever developing non-admin features, as this is enables quickly noting possible user access issues.