Newer
Older
DjangoLDP reference guide
#########################
The DjangoLDP commands
======================
$ djangoldp --help
Usage: djangoldp [OPTIONS] COMMAND [ARGS]...
DjangoLDP CLI
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
configure Configure the project.
initserver Start a DjangoLDP server.
install Install project dependencies.
runserver Run the Django embeded webserver.
startpackage Start a DjangoLDP package.
The `djangoldp` server is built ontop of `django` framework. The `django` core commands are also available. Check `python manage.py --help` and `the official Django documentation <https://docs.djangoproject.com/en/2.2/>`__.
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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
The Initserver command
----------------------
This command initiate a new server folder from a template. It has the minimal option to work out of the box.
The Configure command
---------------------
This is a command meant to tell the server the settings have changed and it must run some maintenance operations and data integrity check, such as the model migration of the LDP packages.
It has options to create new administrator users during the configuration process.
The Install command
-------------------
This command parses the `dependencies` section of the configuration file and install all python distribution required by the project. It is a wrapper around the `requirements.txt` file.
The runserver command
---------------------
This command loads the configuration and starts the LDP server. It is a wrapper around the `django-admin runserver` command.
The startpackage command
------------------------
This a helper command working the same way the `django startpackage` does command. It creates a folder with a DjangoLPD package template.
The DjangoLDP configuration file
================================
The server comes with a default `settings.yml` you can customize.
It contains 3 main sections:
* `dependencies`: contains a list of dependencies to install with pip during the `install` phase
* `ldppackages`: contains a list of djangoldp packages to activate
* `server`: contains all the configuration required by djangoldp server
You need to restart the server after a change in configuration.
The Dependencies section
------------------------
This is not mandatory as you can install all your dependencies manually. But it is convienent to have all in one file when exchanging server configurations.
The format for dependencies is the one accepted by pip. For example:
.. code-block:: yml
dependencies:
- git+https://git.startinblox.com/djangoldp-packages/djangoldp-account.git
As for any python project when you declare a dependency you have to make sure it is installed. You can use the wrapper command `djangoldp install` for this.
The LDP packages section
------------------------
When you want to use a LDP package you need to reference it in the configuration. For example:
.. code-block:: yml
ldppackages:
- djangoldp_account
The name referenced there must be the name of the python module, the one your would use with the `import` statement.
Some packages may require some configuration to work properly. It is a good practice to run the `djangoldp configure` command after adding or upgrading a LDP package.
Here you have :
* `a list of all the package available <https://git.startinblox.com/djangoldp-packages/>`__
* `Explanation on how to make one <https://docs.startinblox.com/import_documentation/develop-sib-ldp-packages.html>`__
If the description of the available packages is unclear, open an issue to ask for more description.
The Server section
------------------
This section contains all parameters to the server itself. All this section is loaded as a Django configuration object to initialize the server.
see https://docs.djangoproject.com/fr/2.2/topics/settings/ for a detail explanation of all settings
The server parameters can be changed at different levels. They are overriden in the following order:
1. The DjangoLDP core default settings
2. :ref:`The DjangoLDP package settings`
3. The code from :ref:`the extra settings module`
4. The `server` section of the YAML settings file
Which means a value written in the server section of `settings.yml` will override any parameters given by the core or the djangoldp packages.
The `MIDDLEWARE` and `INSTALLED_APPS` parameters make exception to that behavior. Those lists are extended from previous values instead of being rewritten. When duplicated entries are detected in those settings, only the first items present in the list are kept.
The extra settings module
-------------------------
The `settings.yml` server section doesn't support dynamical configuration. When this is required, python code for configuration can also be loaded from a `settings.py` module along with the `settings.yml`.
The DjangoLDP package settings
==============================
The DjangoLDP packages support settings declaration through a special `djangoldp_settings.py` at the module's root. This file is fetched by the djangoldp core at runtime and all parameters are loaded following the settings resolution order. (see :ref:`The server section`)
.. code-block:: python
# cat mypkg/mypkg/djangoldp_settings.py
MIDDLEWARE = []
MYPACKAGE_VAR = 'MY_DEFAULT_VAR'