Skip to content

Commit bdabca5

Browse files
annashamrayannashamray
committed
📝 [maykinmedia/django-setup-configuration#1] document setup_configuration command and env vars
1 parent d1cab3b commit bdabca5

File tree

3 files changed

+144
-0
lines changed

3 files changed

+144
-0
lines changed

‎docs/installation/config.rst

+8
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,14 @@ variables. The user will only be created if it doesn't exist yet.
115115
which means the superuser will be created _without_ password. Only has an effect
116116
if ``OBJECTS_SUPERUSER_USERNAME`` is set.
117117

118+
Initial configuration
119+
---------------------
120+
121+
Both Objects API and Objecttypes API support `setup_configuration` management command,
122+
which allows configuration via environment variables.
123+
All these environment variables are described at :ref:`command line <installation_config_cli>`.
124+
125+
118126
Specifying the environment variables
119127
=====================================
120128

‎docs/installation/config_cli.rst

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
.. _installation_config_cli:
2+
3+
4+
===================
5+
Configuration (CLI)
6+
===================
7+
8+
After deploying Objecttypes API and Objects API, they need to be configured to be fully functional. The
9+
command line tool ``setup_configuration`` assist with this configuration:
10+
11+
* It uses environment variables for all configuration choices, therefore you can integrate this with your
12+
infrastructure tooling such as init containers and/or Kubernetes Jobs.
13+
* The command can self-test the configuration to detect problems early on
14+
15+
You can get the full command documentation with:
16+
17+
.. code-block:: bash
18+
19+
src/manage.py setup_configuration --help
20+
21+
.. warning:: This command is declarative - if configuration is manually changed after
22+
running the command and you then run the exact same command again, the manual
23+
changes will be reverted.
24+
25+
Preparation
26+
===========
27+
28+
The command executes the list of pluggable configuration steps, and each step
29+
required specific environment variables, that should be prepared.
30+
Here is the description of all available configuration steps and the environment variables,
31+
use by each step for both APIs.
32+
33+
34+
Objects API
35+
===========
36+
37+
Sites configuration
38+
-------------------
39+
40+
Configure the domain where Objects API is hosted
41+
42+
* ``SITES_CONFIG_ENABLE``: enable Site configuration. Defaults to ``True``.
43+
* ``OBJECTS_DOMAIN``: a ``[host]:[port]`` or ``[host]`` value. Required.
44+
* ``OBJECTS_ORGANIZATION``: name of Objects API organization. Required.
45+
46+
Objecttypes configuration
47+
-------------------------
48+
49+
Objects API uses Objecttypes API to validate data against JSON schemas, therefore
50+
it should be able to request Objecttypes API.
51+
52+
* ``OBJECTS_OBJECTTYPES_CONFIG_ENABLE``: enable Objecttypes configuration. Defaults
53+
to ``True``.
54+
* ``OBJECTTYPES_API_ROOT``: full URL to the Objecttypes API root, for example
55+
``https://objecttypes.gemeente.local/api/v1/``. Required.
56+
* ``OBJECTTYPES_API_OAS``: full URL to the Objecttypes OpenAPI specification.
57+
* ``OBJECTS_OBJECTTYPES_TOKEN``: authorization token. Required.
58+
* ``OBJECTS_OBJECTTYPES_PERSON``: Objects API contact person. Required.
59+
* ``OBJECTS_OBJECTTYPES_EMAIL``: Objects API contact email. Required.
60+
61+
Demo user configuration
62+
-----------------------
63+
64+
Demo user can be created to check if Objects API work. It has superuser permissions,
65+
so its creation is not recommended on production environment.
66+
67+
* ``DEMO_CONFIG_ENABLE``: enable demo user configuration. Defaults to the value of the ``DEBUG`` setting.
68+
* ``DEMO_PERSON``: demo user contact person. Required.
69+
* ``DEMO_EMAIL``: demo user email. Required.
70+
* ``DEMO_TOKEN``: demo token. Required.
71+
72+
73+
Objecttypes API
74+
===============
75+
76+
ObjectTypes API has similar configuration steps as the Objects API.
77+
78+
Sites configuration
79+
-------------------
80+
81+
Configure the domain where Objects API is hosted
82+
83+
* ``SITES_CONFIG_ENABLE``: enable Site configuration. Defaults to ``True``.
84+
* ``OBJECTTYPES_DOMAIN``: a ``[host]:[port]`` or ``[host]`` value. Required.
85+
* ``OBJECTTYPES_ORGANIZATION``: name of Objecttypes API organization. Required.
86+
87+
Objects configuration
88+
---------------------
89+
90+
Objects API uses Objecttypes API to validate data against JSON schemas, therefore
91+
it should be able to request Objecttypes API.
92+
93+
* ``OBJECTS_OBJECTTYPES_CONFIG_ENABLE``: enable Objecttypes configuration. Defaults
94+
to ``True``.
95+
* ``OBJECTTYPES_API_ROOT``: full URL to the Objecttypes API root, for example
96+
``https://objecttypes.gemeente.local/api/v1/``. Required.
97+
* ``OBJECTTYPES_API_OAS``: full URL to the Objecttypes OpenAPI specification.
98+
* ``OBJECTS_OBJECTTYPES_TOKEN``: authorization token. Required.
99+
100+
Demo user configuration
101+
-----------------------
102+
103+
The similar configuration as in Objects API.
104+
105+
* ``DEMO_CONFIG_ENABLE``: enable demo user configuration. Defaults to the value of the ``DEBUG`` setting.
106+
* ``DEMO_PERSON``: demo user contact person. Required.
107+
* ``DEMO_EMAIL``: demo user email. Required.
108+
* ``DEMO_TOKEN``: demo token. Required.
109+
110+
111+
Execution
112+
=========
113+
114+
115+
With the full command invocation, everything is configured at once and immediately
116+
tested.
117+
118+
.. code-block:: bash
119+
120+
src/manage.py setup_configuration
121+
122+
123+
You can skip the self-tests by using the ``--no-selftest`` flag.
124+
125+
.. code-block:: bash
126+
127+
src/manage.py setup_configuration --no-self-test
128+
129+
130+
``setup_configuration`` command checks if the configuration already exists before changing it.
131+
If you want to change some of the values of the existing configuration you can use ``--overwrite`` flag.
132+
133+
.. code-block:: bash
134+
135+
src/manage.py setup_configuration --overwrite

‎docs/installation/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,6 @@ this.
1616

1717
quickstart
1818
config
19+
config_cli
1920
deployment/index
2021
oidc

0 commit comments

Comments
 (0)