Coverage for gws-app/gws/server/__init__.py: 100%

1"""Configuration and control of the embedded servers. 

2 

3GWS runs several servers in the container: the uWSGI web server, which handles 

4client and API requests, the uWSGI spool server, which runs background jobs and 

5the monitor, the frontend NGINX proxy and, in a container, an ``rsyslogd`` 

6daemon for logging. This package configures these servers, creates their 

7configuration files and the start script, and handles server starts, reloads 

8and reconfigurations. 

9 

10Submodules: 

11 

12- ``core``: the ``server`` section of the application configuration 

13 (``Config`` and the configs for the web and spool servers, the monitor, 

14 logging and QGIS). 

15- ``manager``: the server manager (``gws.ServerManager``), which applies config 

16 defaults and environment overrides and renders the configuration files and 

17 the start script from templates. 

18- ``control``: functions that start, reconfigure and reload the servers, and 

19 test the configuration. 

20- ``cli``: the ``server`` command-line commands, which delegate to ``control``. 

21- ``monitor``: the server monitor (``gws.ServerMonitor``), which watches 

22 configuration files and runs periodic tasks. 

23- ``spool``: the spool server application and the job queue functions. 

24- ``uwsgi_module``: access to the ``uwsgi`` module, which only exists inside 

25 a uWSGI process. 

26- ``templates``: default templates for the nginx, uWSGI and syslog configs and 

27 the start script. 

28 

29The configuration files are rendered from templates, which can be replaced in 

30the ``server.templates`` config. These template subjects are used: 

31 

32- ``server.rsyslog_config``: the embedded ``rsyslogd`` daemon, only in a container 

33- ``server.uwsgi_config``: the uWSGI backends, the ``uwsgi`` argument holds the 

34 backend name (``web`` or ``spool``) 

35- ``server.nginx_config``: the frontend NGINX proxy 

36- ``server.start_script``: the shell script that starts the servers 

37 

38Each template receives a :obj:`gws.server.manager.TemplateArgs` object as 

39arguments. By default, text-only templates from the ``templates`` directory 

40are used. 

41 

42The startup sequence is the following: 

43 

44- the main script ``bin/gws`` invokes the ``server start`` command in :obj:`gws.server.cli` 

45- the CLI delegates to :obj:`gws.server.control` 

46- ``control`` configures the application (:obj:`gws.base.application.core.Object`) 

47 and stores the configuration 

48- the application creates the server manager (:obj:`gws.server.manager.Object`) 

49 and the monitor (:obj:`gws.server.monitor.Object`) 

50- ``control`` makes the manager write the configuration files for the servers 

51 and the start script 

52- control returns to ``bin/gws``, which executes the start script 

53- the script starts ``rsyslogd``, the uWSGI backends and finally NGINX, which 

54 keeps running in the foreground 

55 

56On configure, the manager fills in the defaults of the ``server`` config and 

57its subsections, maps the deprecated ``enabled`` keys to ``withWeb``, 

58``withSpool`` and ``withMonitor``, and applies overrides from the environment 

59variables ``GWS_LOG_LEVEL``, ``GWS_WEB_WORKERS`` and ``GWS_SPOOL_WORKERS``. 

60 

61Besides the start, ``control`` supports these workflows: 

62 

63- reconfigure (``server reconfigure``): configure the 

64 application, store the configuration, rewrite the server configs, empty the 

65 transient directory, reload the uWSGI backends and NGINX 

66- reload (``server reload``): empty the transient directory, 

67 reload the uWSGI backends and NGINX 

68- configure (``server configure``, for debugging): configure the application 

69 and store the configuration 

70- config test (``server configtest``, for debugging): configure or only parse 

71 the configuration and log the report 

72 

73The spool server loads the stored configuration and starts the monitor, if 

74``withMonitor`` is set. A uWSGI timer calls the monitor every few seconds. When watched files change, or when an object calls 

75``schedule_reload``, the monitor configures and stores the configuration (on 

76a reconfigure) and reloads the web and spool backends. It does not rewrite the 

77server configs and does not reload NGINX. 

78 

79Example:: 

80 

81 server { 

82 withSpool true 

83 spool { workers 2 timeout 600 } 

84 web { workers 8 maxRequestLength 50 } 

85 log { level "DEBUG" } 

86 qgis { host "qgis" port 80 } 

87 timeZone "Europe/Berlin" 

88 } 

89 

90Example:: 

91 

92 root.app.monitor.register_periodic_task(self, frequency=60) 

93 root.app.monitor.schedule_reload(with_reconfigure=True) 

94""" 

95 

96from .core import Config