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.
To get started, install the OS dependencies, PostgreSQL >=11 and Python >=3.8.
$ sudo utility/install_os_dependencies.sh
$ sudo utility/install_python.sh
$ sudo utility/install_postgres.sh
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
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
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 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.
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", all with the password "password".
$ ./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.