installation.rst

Database
~~~~~~~~

Make sure that PostgreSQL is installed and running and that a database
with user is set up. A good guide how to do this can be found
`here `__
(NOTE: stop before the ‘Update settings’ part).

Python version
~~~~~~~~~~~~~~

Make sure you’re using Python 3.5. You are strongly encouraged to use a
`virtual environment `__.

.. code:: shell

$ pyvenv scipostenv
$ source scipostenv/bin/activate

Now install dependencies:

.. code:: shell

(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 now run:

.. code:: shell

(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. The minimum
required structure is as follows (please mind the non-empty, but still
invalid ``SECRET_KEY``):

.. code:: json

{
"SECRET_KEY": "",
"DB_NAME": "",
"DB_USER": "",
"DB_PWD": ""
}

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

.. code:: shell

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

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

.. code:: shell

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

One can of course also add this variable to the ``~/.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:

.. code:: python

# 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``.

.. code:: shell

(scipostenv) $ ./manage.py send_mails

Check, double check
~~~~~~~~~~~~~~~~~~~

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

.. code:: shell

(scipostenv) $ ./manage.py check

Module bundler
~~~~~~~~~~~~~~

`Webpack `__ takes care of assets in the
``scipost/static/scipost/assets`` folder. To (re)compile all assets into
the ``static_bundles`` folder, simply run:

.. code:: shell

(scipostenv) $ npm run webpack

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:

.. code:: shell

(scipostenv) $ npm run webpack-live

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 /www.getbootstrap.com/>`__. 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.

Collectstatic
~~~~~~~~~~~~~

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

.. code:: shell

(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:

.. code:: shell

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

Create and run migrations
~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code:: shell

(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:

.. code:: shell

(scipostenv) $ ./manage.py createsuperuser

Create groups and permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code:: shell

(scipostenv) $ ./manage.py add_groups_and_permissions

Run server
~~~~~~~~~~

You are now ready to run the server:

.. code:: shell

(scipostenv) $ ./manage.py runserver

Contributors
------------

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

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:

.. code:: shell

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

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

.. code:: shell

(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.