installation.rst 3.66 KB
Newer Older
BERJON Matthieu's avatar
BERJON Matthieu committed
1
2
3
4
5
.. _installation:

Installation
============

BERJON Matthieu's avatar
BERJON Matthieu committed
6
7
8
9
This Django application can be run locally or through a django container. The
application has one set of settings that can be overriden
(:ref:`environment-variable-label`) and satisfies a production type
configuration (:ref:`production-environment-label`) .
BERJON Matthieu's avatar
BERJON Matthieu committed
10
11
12
13
14


Dependencies
------------

BERJON Matthieu's avatar
BERJON Matthieu committed
15
16
17
18
19
20
Mandatory
^^^^^^^^^

- python 3.4 or newer
- Django 1.11
- Django-allauth 0.35.0
BERJON Matthieu's avatar
BERJON Matthieu committed
21
- mysql v15.1 or newer
BERJON Matthieu's avatar
BERJON Matthieu committed
22
23
24
25
26
- python3-mysql

Optional
^^^^^^^^

27
28
For development purposes you can install optional dependencies such as
Sphinx. They can be installed through pip.
BERJON Matthieu's avatar
BERJON Matthieu committed
29
30
31

.. code-block:: bash

32
  pip install sphinx
BERJON Matthieu's avatar
BERJON Matthieu committed
33
34
35
36
37


Development environment
-----------------------

38
39
The configuraton of Allgo is set using environment variables and there is a
default value for most of them.
BERJON Matthieu's avatar
BERJON Matthieu committed
40

41
42
Some variables are overriden in the `docker-compose.yml` so as to provide an
environment suitable for development.
BERJON Matthieu's avatar
BERJON Matthieu committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

For a detailled list of all environment variables, please refer to
:ref:`environment-variable-label`.

.. code-block:: bash

  # run the application
  python manage.py runserver

  # The application can be reached at http://localhost:8000

.. todo::
  
  ensure the use of https protocol by generating or using appropriate
  certificates. More information at
  https://docs.djangoproject.com/fr/1.11/topics/security/

Docker
^^^^^^

When the application is launched within the docker container, it can be reached
at https://localhost/django.

.. warning::

  The environement variables can be declared wherever you feel the best and
  can be managed at the docker-compose level for example.

Database
^^^^^^^^

.. warning::

  because we depend at the moment on a legacy database we have a specific 
  setup for Django. We have chose to recreate the database into Django and by 
  integrating the database constraints (that are managed by Ruby on Rails and
  not the SGDB).

At the moment the django docker container take care of the migration by calling
the migration script. The migration process consist of two files located int
`tools` folder:

- `migration2django.sql`: sql file executing the migration
- `migration.sh`: script executing the migration and setting up the Django
  application

You can run manually the migration using `migration.sh`:

.. code-block:: bash
  
  # If exists, will delete django app related tables
  ./tools/migration.sh -d USER [PASSWORD] HOST DB

  # Dump the current rails tables
  ./tools/migration.sh -e USER [PASSWORD] HOST DB

  # Create Django tables, execute the migration, set up django
  ./tools/migrations.sh -m USER [PASSWORD] HOST DB

  # Help
  ./tools/migrations.sh -h
BERJON Matthieu's avatar
BERJON Matthieu committed
104

BERJON Matthieu's avatar
BERJON Matthieu committed
105
106
107
108
109
110
111
112
The migration script works only on Unix related operating system as it saves
the database tables in the `/tmp` folder.

.. _production-environment-label:

Production environment
-----------------------

113
114
By default, the `config/env.py` is setup for a production config and
requires to setup at minimum one environment variable:
BERJON Matthieu's avatar
BERJON Matthieu committed
115

116
117
- `ALLGO_ALLOWED_HOSTS` to be set to the hostname where this allgo instance is
  reachable
BERJON Matthieu's avatar
BERJON Matthieu committed
118
119
120
121
122
123
124
125
126
127


Docker setup
^^^^^^^^^^^^

The actual docker setup relies on a Debian stretch image and Stretch backport.
The different configuration file for the docker file such as the nginx
configuration in the `setup/dk` directory. This includes:

- `allgo.conf`: nginx configuration for the django docker
128
- `container_init`: initialisation of the container
BERJON Matthieu's avatar
BERJON Matthieu committed
129
- `nginx.patch`: main nginx configuration
130
131
- `run-allgo`: bash script creating the necessary directories and running the
  different services necessary for the application
BERJON Matthieu's avatar
BERJON Matthieu committed
132
133
134
135
136
137
138
139
140

.. _environment-variable-label:

Environment variables
---------------------

.. warning::

  All environment variables **must** be prefixed by `ALLGO`.
BERJON Matthieu's avatar
BERJON Matthieu committed
141

142
143
.. automodule:: config.env