Installing SciPost¶

This guide will walk you through a basic installation of the SciPost platform.

Database¶

SciPost runs on the Postgresql relational database.

Make sure that PostgreSQL 9.4 (or higher) is installed (see instructions) and running on your system.

You will need to create a database user. You can find many guides online on how to do this.

Postgres creates a user postgres by default. Start a shell session for this user:
```
$ sudo su - postgres
```
Log into a postgres session:
```
$ psql
```
Create the database (let’s assume from now on that you’ll call your database scipost_database):
```
CREATE DATABASE scipost_database;
```
Create the database user which SciPost will use to connect and interact with the database:
```
CREATE USER scipost_db_user WITH PASSWORD [password];
```

Give needed privileges to the user:

GRANT ALL PRIVILEGES ON DATABASE scipost_database TO scipost_db_user;

To enable testing, also give the CREATEDB permission to the user:
```
ALTER USER scipost_db_user CREATEDB;
```
Quit postgres session:
```
\q
```
Go back to your regular user’s shell session:
```
$ exit
```

You will need the database username and password in your basic Django settings below.

Python version¶

Python comes in multiple versions, which in principle can lead to lots of incompatibility problems on your system. Thankfully there exists a nifty version management system, pyenv. This allows you to hold multiple versions on your system, and determine locally/globally which ones should be used.

SciPost runs on Python 3.5. You are strongly encouraged to use a virtual environment:

$ pyvenv scipostenv
$ source scipostenv/bin/activate

(N.B.: this is Python 3.5-specific; for 3.6 and above, pyvenv has been deprecated in favour of using python -m venv [path to new venv]).

Now install dependencies:

(scipostenv) $ pip install -r requirements.txt

Frontend dependencies¶

NPM (version 5.x; tested on v5.3.0) will take care of frontend dependencies. To install all packages, run:

(scipostenv) $ npm install

Settings¶

In this project, many settings are not sensitive and are thus tracked using Git. Some settings are however secret. These settings may be saved into the secrets.json file in the root of the project (you should of course ensure that this file is excluded from the Git repository). The minimum required structure is as follows (you’ll have to generate your own SECRET_KEY; the database name, user and password are the ones you set up in Database above; the CELERY_BROKER_URL can be left blank for now):

{
  "SECRET_KEY": "<key>",
  "DB_NAME": "",
  "DB_USER": "",
  "DB_PWD": "",
  "CELERY_BROKER_URL": "",
  "DISCOURSE_SSO_SECRET": ""
}

The settings file itself is saved into SciPost_v1/settings/local_<name>.py. Be sure to wildcard import the base.py file at the top of your settings file. To run the server, use one of two ways. Either:

(scipostenv) $ ./manage.py runserver --settings=SciPost_v1.settings.local_<name>

… or for convenience, export the same settingsfile path to the DJANGO_SETTINGS_MODULE variable, so that one can run the django commands by default:

(scipostenv) $ export DJANGO_SETTINGS_MODULE="SciPost_v1.settings.local_<name>"

One can of course also add this variable to your ~/.bash_profile for convenience.

Mail¶

In the mails application a special Email Backend is defined. This will write all emails to the database. To use this backend, in the settings set the the variable EMAIL_BACKEND as:

# settings.py
EMAIL_BACKEND = 'mails.backends.filebased.ModelEmailBackend'
EMAIL_BACKEND_ORIGINAL = 'mails.backends.filebased.EmailBackend'

A management command is defined to send the unsent mails in the database. This management command uses the Email Backend defined in the settings under variable EMAIL_BACKEND_ORIGINAL. If not defined, this defaults to the Django default: django.core.mail.backends.smtp.EmailBackend:

(scipostenv) $ ./manage.py send_mails

Checks¶

To make sure everything is set up and correctly configured, run:

(scipostenv) $ ./manage.py check

Module bundler¶

Webpack takes care of assets in the scipost/static/scipost/assets folder.

Separate configurations are defined for development and production servers. For development, the configuration file is webpack.dev.config.js, while for production it is webpack.prod.config.js.

The file package.json defines the scripts needed to run npm below.

During development, to (re)compile all assets into the static_bundles folder, simply run:

(scipostenv) $ npm run webpack-dev

which makes use of the dev config file webpack.dev.config.js.

While editing assets, it may be helpful to put Webpack in watch mode. This will recompile your assets in real time. To do so, instead of the above command, run:

(scipostenv) $ npm run webpack-dev-live

On the production server, run:

(scipostenv) $ npm run webpack-prod

which makes use of the prod config file webpack.prod.config.js.

There is no need to run npm in watch mode (there is no reason for live editing of assets on production).

Sass and Bootstrap¶

Styling will mainly be configured using .scss files in the scipost/static/scipost/scss/preconfig.scss file, relying on Bootstrap v4.0.0-beta. A full list of variables available by default can be found here. All modules are configured in the .bootstraprc file. All modules are disabled by default.

Static assets¶

In order to collect static files from all INSTALLED_APPS (i.e. the assets managed by Webpack), run:

(scipostenv) $ ./manage.py collectstatic

This will put all static files in the STATIC_ROOT folder defined in your settings file. If needed, you can remove stale static files through:

(scipostenv) $ ./manage.py collectstatic --clear

Create and run migrations¶

Now that everything is set up, we can create the relevant tables in the database:

(scipostenv) $ ./manage.py migrate

Create a superuser¶

In order to use the admin site, you’ll need a superuser account, which can be created using:

(scipostenv) $ ./manage.py createsuperuser

Create groups and permissions¶

Groups and their respective permissions are set using the management command:

(scipostenv) $ ./manage.py add_groups_and_permissions

Run server¶

You are now ready to run the server:

(scipostenv) $ ./manage.py runserver

Contributors¶

Users of the SciPost portal are known as Contributors and are usually created through the registration form accessible from the home page.

Finish setting up your first Contributor¶

After groups have been defined, you can finish setting up your first Contributor from your superuser created just above:

(scipostenv) $ ./manage.py setup_contributor --username=[username you used for the db su]

Other Contributors¶

You can create a number of users, and use the admin site to give them various permissions through memberships of certain groups. For example, you’ll want members of the SciPost Administrators and Editorial Administrators groups in order to access the internal management and editorial tools.

Initial data¶

If you’re working on an (almost) empty test database, you can easily fill it using one of the built-in commands. To create a few instances for each available object, simply run:

(scipostenv) $ ./manage.py populate_db --all

Run the same command with the --help argument to find arguments to create instances for individual models:

(scipostenv) $ ./manage.py populate_db --help

Maintaining database migrations¶

Every time fields in any of the models change, a database migration needs to be created and applied. The first documents a database change and its inverse, the second actually changes the database.

Make sure to commit the migration to Git after applying it, so other developers can use them.:

(scipostenv) $ ./manage.py makemigrations
(scipostenv) $ ./manage.py migrate

Search engine¶

Django Haystack is used to handle search queries. The search engine needs indexing before you can use it:

(scipostenv) $ ./manage.py update_index -u default

Models involved in searches are re-indexed using post_save signals. [TO BE UPDATED: celery setup].

Django-extensions¶

django-extensions provide added commands like ./manage.py shell_plus, which preloads all models in a shell session. Additional imports may be specified in settings.py as follows:

SHELL_PLUS_POST_IMPORTS = (
    ('theses.factories', ('ThesisLinkFactory')),
    ('comments.factories', ('CommentFactory')),
)