Coverage for cc_modules/cc_config.py: 62%

1# noinspection HttpUrlsUsage 

2""" 

3camcops_server/cc_modules/cc_config.py 

4 

5=============================================================================== 

6 

7 Copyright (C) 2012, University of Cambridge, Department of Psychiatry. 

8 Created by Rudolf Cardinal (rnc1001@cam.ac.uk). 

9 

10 This file is part of CamCOPS. 

11 

12 CamCOPS is free software: you can redistribute it and/or modify 

13 it under the terms of the GNU General Public License as published by 

14 the Free Software Foundation, either version 3 of the License, or 

15 (at your option) any later version. 

16 

17 CamCOPS is distributed in the hope that it will be useful, 

18 but WITHOUT ANY WARRANTY; without even the implied warranty of 

19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

20 GNU General Public License for more details. 

21 

22 You should have received a copy of the GNU General Public License 

23 along with CamCOPS. If not, see <https://www.gnu.org/licenses/>. 

24 

25=============================================================================== 

26 

27**Read and represent a CamCOPS config file.** 

28 

29Also contains various types of demonstration config file (CamCOPS, but also 

30``supervisord``, Apache, etc.) and demonstration helper scripts (e.g. MySQL). 

31 

32There are CONDITIONAL AND IN-FUNCTION IMPORTS HERE; see below. This is to 

33minimize the number of modules loaded when this is used in the context of the 

34client-side database script, rather than the webview. 

35 

36Moreover, it should not use SQLAlchemy objects directly; see ``celery.py``. 

37 

38In particular, I tried hard to use a "database-unaware" (unbound) SQLAlchemy 

39ExportRecipient object. However, when the backend re-calls the config to get 

40its recipients, we get errors like: 

41 

42.. code-block:: none 

43 

44 [2018-12-25 00:56:00,118: ERROR/ForkPoolWorker-7] Task camcops_server.cc_modules.celery_tasks.export_to_recipient_backend[ab2e2691-c2fa-4821-b8cd-2cbeb86ddc8f] raised unexpected: DetachedInstanceError('Instance <ExportRecipient at 0x7febbeeea7b8> is not bound to a Session; attribute refresh operation cannot proceed',) 

45 Traceback (most recent call last): 

46 File "/home/rudolf/dev/venvs/camcops/lib/python3.6/site-packages/celery/app/trace.py", line 382, in trace_task 

47 R = retval = fun(*args, **kwargs) 

48 File "/home/rudolf/dev/venvs/camcops/lib/python3.6/site-packages/celery/app/trace.py", line 641, in __protected_call__ 

49 return self.run(*args, **kwargs) 

50 File "/home/rudolf/Documents/code/camcops/server/camcops_server/cc_modules/celery_tasks.py", line 103, in export_to_recipient_backend 

51 schedule_via_backend=False) 

52 File "/home/rudolf/Documents/code/camcops/server/camcops_server/cc_modules/cc_export.py", line 255, in export 

53 req, recipient_names=recipient_names, all_recipients=all_recipients) 

54 File "/home/rudolf/Documents/code/camcops/server/camcops_server/cc_modules/cc_config.py", line 1460, in get_export_recipients 

55 valid_names = set(r.recipient_name for r in recipients) 

56 File "/home/rudolf/Documents/code/camcops/server/camcops_server/cc_modules/cc_config.py", line 1460, in <genexpr> 

57 valid_names = set(r.recipient_name for r in recipients) 

58 File "/home/rudolf/dev/venvs/camcops/lib/python3.6/site-packages/sqlalchemy/orm/attributes.py", line 242, in __get__ 

59 return self.impl.get(instance_state(instance), dict_) 

60 File "/home/rudolf/dev/venvs/camcops/lib/python3.6/site-packages/sqlalchemy/orm/attributes.py", line 594, in get 

61 value = state._load_expired(state, passive) 

62 File "/home/rudolf/dev/venvs/camcops/lib/python3.6/site-packages/sqlalchemy/orm/state.py", line 608, in _load_expired 

63 self.manager.deferred_scalar_loader(self, toload) 

64 File "/home/rudolf/dev/venvs/camcops/lib/python3.6/site-packages/sqlalchemy/orm/loading.py", line 813, in load_scalar_attributes 

65 (state_str(state))) 

66 sqlalchemy.orm.exc.DetachedInstanceError: Instance <ExportRecipient at 0x7febbeeea7b8> is not bound to a Session; attribute refresh operation cannot proceed (Background on this error at: http://sqlalche.me/e/bhk3) 

67 

68""" # noqa 

69 

70import codecs 

71import collections 

72import configparser 

73import contextlib 

74import datetime 

75import os 

76import logging 

77import re 

78from subprocess import run, PIPE 

79from typing import Any, Dict, Generator, List, Optional, Union 

80 

81from cardinal_pythonlib.classes import class_attribute_values 

82from cardinal_pythonlib.configfiles import ( 

83 get_config_parameter, 

84 get_config_parameter_boolean, 

85 get_config_parameter_loglevel, 

86 get_config_parameter_multiline, 

87) 

88from cardinal_pythonlib.docker import running_under_docker 

89from cardinal_pythonlib.fileops import relative_filename_within_dir 

90from cardinal_pythonlib.logs import BraceStyleAdapter 

91from cardinal_pythonlib.randomness import create_base64encoded_randomness 

92from cardinal_pythonlib.reprfunc import auto_repr 

93from cardinal_pythonlib.sqlalchemy.alembic_func import ( 

94 get_current_and_head_revision, 

95) 

96from cardinal_pythonlib.sqlalchemy.engine_func import ( 

97 is_sqlserver, 

98 is_sqlserver_2008_or_later, 

99) 

100from cardinal_pythonlib.sqlalchemy.logs import ( 

101 pre_disable_sqlalchemy_extra_echo_log, 

102) 

103from cardinal_pythonlib.sqlalchemy.schema import get_table_names 

104from cardinal_pythonlib.sqlalchemy.session import get_safe_url_from_engine 

105from cardinal_pythonlib.wsgi.reverse_proxied_mw import ReverseProxiedMiddleware 

106import celery.schedules 

107from sqlalchemy.engine import create_engine 

108from sqlalchemy.engine.base import Engine 

109from sqlalchemy.orm import sessionmaker 

110from sqlalchemy.orm import Session as SqlASession 

111 

112from camcops_server.cc_modules.cc_baseconstants import ( 

113 ALEMBIC_BASE_DIR, 

114 ALEMBIC_CONFIG_FILENAME, 

115 ALEMBIC_VERSION_TABLE, 

116 ENVVAR_CONFIG_FILE, 

117 LINUX_DEFAULT_MATPLOTLIB_CACHE_DIR, 

118 ON_READTHEDOCS, 

119) 

120from camcops_server.cc_modules.cc_cache import cache_region_static, fkg 

121from camcops_server.cc_modules.cc_constants import ( 

122 CONFIG_FILE_EXPORT_SECTION, 

123 CONFIG_FILE_SERVER_SECTION, 

124 CONFIG_FILE_SITE_SECTION, 

125 CONFIG_FILE_SMS_BACKEND_PREFIX, 

126 ConfigDefaults, 

127 ConfigParamExportGeneral, 

128 ConfigParamExportRecipient, 

129 ConfigParamServer, 

130 ConfigParamSite, 

131 DockerConstants, 

132 MfaMethod, 

133 SmsBackendNames, 

134) 

135from camcops_server.cc_modules.cc_exportrecipientinfo import ( 

136 ExportRecipientInfo, 

137) 

138from camcops_server.cc_modules.cc_exception import raise_runtime_error 

139from camcops_server.cc_modules.cc_filename import PatientSpecElementForFilename 

140from camcops_server.cc_modules.cc_language import POSSIBLE_LOCALES 

141from camcops_server.cc_modules.cc_pyramid import MASTER_ROUTE_CLIENT_API 

142from camcops_server.cc_modules.cc_sms import ( 

143 get_sms_backend, 

144 KapowSmsBackend, 

145 TwilioSmsBackend, 

146) 

147from camcops_server.cc_modules.cc_snomed import ( 

148 get_all_task_snomed_concepts, 

149 get_icd9_snomed_concepts_from_xml, 

150 get_icd10_snomed_concepts_from_xml, 

151 SnomedConcept, 

152) 

153from camcops_server.cc_modules.cc_validators import ( 

154 validate_export_recipient_name, 

155 validate_group_name, 

156) 

157from camcops_server.cc_modules.cc_version_string import ( 

158 CAMCOPS_SERVER_VERSION_STRING, 

159) 

160 

161log = BraceStyleAdapter(logging.getLogger(__name__)) 

162 

163pre_disable_sqlalchemy_extra_echo_log() 

164 

165 

166# ============================================================================= 

167# Constants 

168# ============================================================================= 

169 

170VALID_RECIPIENT_NAME_REGEX = r"^[\w_-]+$" 

171# ... because we'll use them for filenames, amongst other things 

172# https://stackoverflow.com/questions/10944438/ 

173# https://regexr.com/ 

174 

175# Windows paths: irrelevant, as Windows doesn't run supervisord 

176DEFAULT_LINUX_CAMCOPS_CONFIG = "/etc/camcops/camcops.conf" 

177DEFAULT_LINUX_CAMCOPS_BASE_DIR = "/usr/share/camcops" 

178DEFAULT_LINUX_CAMCOPS_VENV_DIR = os.path.join( 

179 DEFAULT_LINUX_CAMCOPS_BASE_DIR, "venv" 

180) 

181DEFAULT_LINUX_CAMCOPS_VENV_BIN_DIR = os.path.join( 

182 DEFAULT_LINUX_CAMCOPS_VENV_DIR, "bin" 

183) 

184DEFAULT_LINUX_CAMCOPS_EXECUTABLE = os.path.join( 

185 DEFAULT_LINUX_CAMCOPS_VENV_BIN_DIR, "camcops_server" 

186) 

187DEFAULT_LINUX_CAMCOPS_STATIC_DIR = os.path.join( 

188 DEFAULT_LINUX_CAMCOPS_VENV_DIR, 

189 "lib", 

190 "python3.9", 

191 "site-packages", 

192 "camcops_server", 

193 "static", 

194) 

195DEFAULT_LINUX_LOGDIR = "/var/log/supervisor" 

196DEFAULT_LINUX_USER = "www-data" # Ubuntu default 

197 

198 

199# ============================================================================= 

200# Helper functions 

201# ============================================================================= 

202 

203 

204def warn_if_not_within_docker_dir( 

205 param_name: str, 

206 filespec: str, 

207 permit_cfg: bool = False, 

208 permit_venv: bool = False, 

209 permit_tmp: bool = False, 

210 param_contains_not_is: bool = False, 

211) -> None: 

212 """ 

213 If the specified filename isn't within a relevant directory that will be 

214 used by CamCOPS when operating within a Docker Compose application, warn 

215 the user. 

216 

217 Args: 

218 param_name: 

219 Name of the parameter in the CamCOPS config file. 

220 filespec: 

221 Filename (or filename-like thing) to check. 

222 permit_cfg: 

223 Permit the file to be in the configuration directory. 

224 permit_venv: 

225 Permit the file to be in the virtual environment directory. 

226 permit_tmp: 

227 Permit the file to be in the shared temporary space. 

228 param_contains_not_is: 

229 The parameter "contains", not "is", the filename. 

230 """ 

231 if not filespec: 

232 return 

233 is_phrase = "contains" if param_contains_not_is else "is" 

234 permitted_dirs = [] # type: List[str] 

235 if permit_cfg: 

236 permitted_dirs.append(DockerConstants.CONFIG_DIR) 

237 if permit_venv: 

238 permitted_dirs.append(DockerConstants.VENV_DIR) 

239 if permit_tmp: 

240 permitted_dirs.append(DockerConstants.TMP_DIR) 

241 ok = any(relative_filename_within_dir(filespec, d) for d in permitted_dirs) 

242 if not ok: 

243 log.warning( 

244 f"Config parameter {param_name} {is_phrase} {filespec!r}, " 

245 f"which is not within the permitted Docker directories " 

246 f"{permitted_dirs!r}" 

247 ) 

248 

249 

250def warn_if_not_docker_value( 

251 param_name: str, actual_value: Any, required_value: Any 

252) -> None: 

253 """ 

254 Warn the user if a parameter does not match the specific value required 

255 when operating under Docker. 

256 

257 Args: 

258 param_name: 

259 Name of the parameter in the CamCOPS config file. 

260 actual_value: 

261 Value in the config file. 

262 required_value: 

263 Value that should be used. 

264 """ 

265 if actual_value != required_value: 

266 log.warning( 

267 f"Config parameter {param_name} is {actual_value!r}, " 

268 f"but should be {required_value!r} when running inside " 

269 f"Docker" 

270 ) 

271 

272 

273def warn_if_not_present(param_name: str, value: Any) -> None: 

274 """ 

275 Warn the user if a parameter is not set (None, or an empty string), for 

276 when operating under Docker. 

277 

278 Args: 

279 param_name: 

280 Name of the parameter in the CamCOPS config file. 

281 value: 

282 Value in the config file. 

283 """ 

284 if value is None or value == "": 

285 log.warning( 

286 f"Config parameter {param_name} is not specified, " 

287 f"but should be specified when running inside Docker" 

288 ) 

289 

290 

291def list_to_multiline_string(values: List[Any]) -> str: 

292 """ 

293 Converts a Python list to a multiline string suitable for use as a config 

294 file default (in a pretty way). 

295 """ 

296 spacer = "\n " 

297 gen_values = (str(x) for x in values) 

298 if len(values) <= 1: 

299 return spacer.join(gen_values) 

300 else: 

301 return spacer + spacer.join(gen_values) 

302 

303 

304# ============================================================================= 

305# Demo config 

306# ============================================================================= 

307 

308# Cosmetic demonstration constants: 

309DEFAULT_DB_READONLY_USER = "QQQ_USERNAME_REPLACE_ME" 

310DEFAULT_DB_READONLY_PASSWORD = "PPP_PASSWORD_REPLACE_ME" 

311DUMMY_INSTITUTION_URL = "https://www.mydomain/" 

312 

313 

314def get_demo_config(for_docker: bool = False) -> str: 

315 """ 

316 Returns a demonstration config file based on the specified parameters. 

317 

318 Args: 

319 for_docker: 

320 Adjust defaults for the Docker environment. 

321 """ 

322 # ... 

323 # http://www.debian.org/doc/debian-policy/ch-opersys.html#s-writing-init 

324 # https://people.canonical.com/~cjwatson/ubuntu-policy/policy.html/ch-opersys.html # noqa 

325 session_cookie_secret = create_base64encoded_randomness(num_bytes=64) 

326 

327 cd = ConfigDefaults(docker=for_docker) 

328 return f""" 

329# Demonstration CamCOPS server configuration file. 

330# 

331# Created by CamCOPS server version {CAMCOPS_SERVER_VERSION_STRING}. 

332# See help at https://camcops.readthedocs.io/. 

333# 

334# Using defaults for Docker environment: {for_docker} 

335 

336# ============================================================================= 

337# CamCOPS site 

338# ============================================================================= 

339 

340[{CONFIG_FILE_SITE_SECTION}] 

341 

342# ----------------------------------------------------------------------------- 

343# Database connection 

344# ----------------------------------------------------------------------------- 

345 

346{ConfigParamSite.DB_URL} = {cd.demo_db_url} 

347{ConfigParamSite.DB_ECHO} = {cd.DB_ECHO} 

348 

349# ----------------------------------------------------------------------------- 

350# URLs and paths 

351# ----------------------------------------------------------------------------- 

352 

353{ConfigParamSite.LOCAL_INSTITUTION_URL} = {DUMMY_INSTITUTION_URL} 

354{ConfigParamSite.LOCAL_LOGO_FILE_ABSOLUTE} = {cd.LOCAL_LOGO_FILE_ABSOLUTE} 

355{ConfigParamSite.CAMCOPS_LOGO_FILE_ABSOLUTE} = {cd.CAMCOPS_LOGO_FILE_ABSOLUTE} 

356 

357{ConfigParamSite.EXTRA_STRING_FILES} = {cd.EXTRA_STRING_FILES} 

358{ConfigParamSite.RESTRICTED_TASKS} = 

359{ConfigParamSite.LANGUAGE} = {cd.LANGUAGE} 

360 

361{ConfigParamSite.SNOMED_TASK_XML_FILENAME} = 

362{ConfigParamSite.SNOMED_ICD9_XML_FILENAME} = 

363{ConfigParamSite.SNOMED_ICD10_XML_FILENAME} = 

364 

365{ConfigParamSite.WKHTMLTOPDF_FILENAME} = 

366 

367# ----------------------------------------------------------------------------- 

368# Server geographical location 

369# ----------------------------------------------------------------------------- 

370 

371{ConfigParamSite.REGION_CODE} = {cd.REGION_CODE} 

372 

373# ----------------------------------------------------------------------------- 

374# Login and session configuration 

375# ----------------------------------------------------------------------------- 

376 

377{ConfigParamSite.MFA_METHODS} = {list_to_multiline_string(cd.MFA_METHODS)} 

378{ConfigParamSite.MFA_TIMEOUT_S} = {cd.MFA_TIMEOUT_S} 

379{ConfigParamSite.SESSION_COOKIE_SECRET} = camcops_autogenerated_secret_{session_cookie_secret} 

380{ConfigParamSite.SESSION_TIMEOUT_MINUTES} = {cd.SESSION_TIMEOUT_MINUTES} 

381{ConfigParamSite.SESSION_CHECK_USER_IP} = {cd.SESSION_CHECK_USER_IP} 

382{ConfigParamSite.PASSWORD_CHANGE_FREQUENCY_DAYS} = {cd.PASSWORD_CHANGE_FREQUENCY_DAYS} 

383{ConfigParamSite.LOCKOUT_THRESHOLD} = {cd.LOCKOUT_THRESHOLD} 

384{ConfigParamSite.LOCKOUT_DURATION_INCREMENT_MINUTES} = {cd.LOCKOUT_DURATION_INCREMENT_MINUTES} 

385{ConfigParamSite.DISABLE_PASSWORD_AUTOCOMPLETE} = {cd.DISABLE_PASSWORD_AUTOCOMPLETE} 

386 

387# ----------------------------------------------------------------------------- 

388# Suggested filenames for saving PDFs from the web view 

389# ----------------------------------------------------------------------------- 

390 

391{ConfigParamSite.PATIENT_SPEC_IF_ANONYMOUS} = {cd.PATIENT_SPEC_IF_ANONYMOUS} 

392{ConfigParamSite.PATIENT_SPEC} = {{{PatientSpecElementForFilename.SURNAME}}}_{{{PatientSpecElementForFilename.FORENAME}}}_{{{PatientSpecElementForFilename.ALLIDNUMS}}} 

393 

394{ConfigParamSite.TASK_FILENAME_SPEC} = CamCOPS_{{patient}}_{{created}}_{{tasktype}}-{{serverpk}}.{{filetype}} 

395{ConfigParamSite.TRACKER_FILENAME_SPEC} = CamCOPS_{{patient}}_{{now}}_tracker.{{filetype}} 

396{ConfigParamSite.CTV_FILENAME_SPEC} = CamCOPS_{{patient}}_{{now}}_clinicaltextview.{{filetype}} 

397 

398# ----------------------------------------------------------------------------- 

399# E-mail options 

400# ----------------------------------------------------------------------------- 

401 

402{ConfigParamSite.EMAIL_HOST} = mysmtpserver.mydomain 

403{ConfigParamSite.EMAIL_PORT} = {cd.EMAIL_PORT} 

404{ConfigParamSite.EMAIL_USE_TLS} = {cd.EMAIL_USE_TLS} 

405{ConfigParamSite.EMAIL_HOST_USERNAME} = myusername 

406{ConfigParamSite.EMAIL_HOST_PASSWORD} = mypassword 

407{ConfigParamSite.EMAIL_FROM} = CamCOPS computer <noreply@myinstitution.mydomain> 

408{ConfigParamSite.EMAIL_SENDER} = 

409{ConfigParamSite.EMAIL_REPLY_TO} = CamCOPS clinical administrator <admin@myinstitution.mydomain> 

410 

411# ----------------------------------------------------------------------------- 

412# SMS options 

413# ----------------------------------------------------------------------------- 

414 

415{ConfigParamSite.SMS_BACKEND} = {cd.SMS_BACKEND} 

416 

417# ----------------------------------------------------------------------------- 

418# User download options 

419# ----------------------------------------------------------------------------- 

420 

421{ConfigParamSite.PERMIT_IMMEDIATE_DOWNLOADS} = {cd.PERMIT_IMMEDIATE_DOWNLOADS} 

422{ConfigParamSite.USER_DOWNLOAD_DIR} = {cd.USER_DOWNLOAD_DIR} 

423{ConfigParamSite.USER_DOWNLOAD_FILE_LIFETIME_MIN} = {cd.USER_DOWNLOAD_FILE_LIFETIME_MIN} 

424{ConfigParamSite.USER_DOWNLOAD_MAX_SPACE_MB} = {cd.USER_DOWNLOAD_MAX_SPACE_MB} 

425 

426# ----------------------------------------------------------------------------- 

427# Debugging options 

428# ----------------------------------------------------------------------------- 

429 

430{ConfigParamSite.WEBVIEW_LOGLEVEL} = {cd.WEBVIEW_LOGLEVEL_TEXTFORMAT} 

431{ConfigParamSite.CLIENT_API_LOGLEVEL} = {cd.CLIENT_API_LOGLEVEL_TEXTFORMAT} 

432{ConfigParamSite.ALLOW_INSECURE_COOKIES} = {cd.ALLOW_INSECURE_COOKIES} 

433 

434 

435# ============================================================================= 

436# Web server options 

437# ============================================================================= 

438 

439[{CONFIG_FILE_SERVER_SECTION}] 

440 

441# ----------------------------------------------------------------------------- 

442# Common web server options 

443# ----------------------------------------------------------------------------- 

444 

445{ConfigParamServer.HOST} = {cd.HOST} 

446{ConfigParamServer.PORT} = {cd.PORT} 

447{ConfigParamServer.UNIX_DOMAIN_SOCKET} = 

448 

449# If you host CamCOPS behind Apache, it’s likely that you’ll want Apache to 

450# handle HTTPS and CamCOPS to operate unencrypted behind a reverse proxy, in 

451# which case don’t set SSL_CERTIFICATE or SSL_PRIVATE_KEY. 

452{ConfigParamServer.SSL_CERTIFICATE} = {cd.SSL_CERTIFICATE} 

453{ConfigParamServer.SSL_PRIVATE_KEY} = {cd.SSL_PRIVATE_KEY} 

454{ConfigParamServer.STATIC_CACHE_DURATION_S} = {cd.STATIC_CACHE_DURATION_S} 

455 

456# ----------------------------------------------------------------------------- 

457# WSGI options 

458# ----------------------------------------------------------------------------- 

459 

460{ConfigParamServer.DEBUG_REVERSE_PROXY} = {cd.DEBUG_REVERSE_PROXY} 

461{ConfigParamServer.DEBUG_TOOLBAR} = {cd.DEBUG_TOOLBAR} 

462{ConfigParamServer.SHOW_REQUESTS} = {cd.SHOW_REQUESTS} 

463{ConfigParamServer.SHOW_REQUEST_IMMEDIATELY} = {cd.SHOW_REQUEST_IMMEDIATELY} 

464{ConfigParamServer.SHOW_RESPONSE} = {cd.SHOW_RESPONSE} 

465{ConfigParamServer.SHOW_TIMING} = {cd.SHOW_TIMING} 

466{ConfigParamServer.PROXY_HTTP_HOST} = 

467{ConfigParamServer.PROXY_REMOTE_ADDR} = 

468{ConfigParamServer.PROXY_REWRITE_PATH_INFO} = {cd.PROXY_REWRITE_PATH_INFO} 

469{ConfigParamServer.PROXY_SCRIPT_NAME} = 

470{ConfigParamServer.PROXY_SERVER_NAME} = 

471{ConfigParamServer.PROXY_SERVER_PORT} = 

472{ConfigParamServer.PROXY_URL_SCHEME} = 

473{ConfigParamServer.TRUSTED_PROXY_HEADERS} = 

474 HTTP_X_FORWARDED_HOST 

475 HTTP_X_FORWARDED_SERVER 

476 HTTP_X_FORWARDED_PORT 

477 HTTP_X_FORWARDED_PROTO 

478 HTTP_X_FORWARDED_FOR 

479 HTTP_X_SCRIPT_NAME 

480 

481# ----------------------------------------------------------------------------- 

482# Determining the externally accessible CamCOPS URL for back-end work 

483# ----------------------------------------------------------------------------- 

484 

485{ConfigParamServer.EXTERNAL_URL_SCHEME} = 

486{ConfigParamServer.EXTERNAL_SERVER_NAME} = 

487{ConfigParamServer.EXTERNAL_SERVER_PORT} = 

488{ConfigParamServer.EXTERNAL_SCRIPT_NAME} = 

489 

490# ----------------------------------------------------------------------------- 

491# CherryPy options 

492# ----------------------------------------------------------------------------- 

493 

494{ConfigParamServer.CHERRYPY_SERVER_NAME} = {cd.CHERRYPY_SERVER_NAME} 

495{ConfigParamServer.CHERRYPY_THREADS_START} = {cd.CHERRYPY_THREADS_START} 

496{ConfigParamServer.CHERRYPY_THREADS_MAX} = {cd.CHERRYPY_THREADS_MAX} 

497{ConfigParamServer.CHERRYPY_LOG_SCREEN} = {cd.CHERRYPY_LOG_SCREEN} 

498{ConfigParamServer.CHERRYPY_ROOT_PATH} = {cd.CHERRYPY_ROOT_PATH} 

499 

500# ----------------------------------------------------------------------------- 

501# Gunicorn options 

502# ----------------------------------------------------------------------------- 

503 

504{ConfigParamServer.GUNICORN_NUM_WORKERS} = {cd.GUNICORN_NUM_WORKERS} 

505{ConfigParamServer.GUNICORN_DEBUG_RELOAD} = {cd.GUNICORN_DEBUG_RELOAD} 

506{ConfigParamServer.GUNICORN_TIMEOUT_S} = {cd.GUNICORN_TIMEOUT_S} 

507{ConfigParamServer.DEBUG_SHOW_GUNICORN_OPTIONS} = {cd.DEBUG_SHOW_GUNICORN_OPTIONS} 

508 

509 

510# ============================================================================= 

511# Export options 

512# ============================================================================= 

513 

514[{CONFIG_FILE_EXPORT_SECTION}] 

515 

516{ConfigParamExportGeneral.CELERY_BEAT_EXTRA_ARGS} = 

517{ConfigParamExportGeneral.CELERY_BEAT_SCHEDULE_DATABASE} = {cd.CELERY_BEAT_SCHEDULE_DATABASE} 

518{ConfigParamExportGeneral.CELERY_BROKER_URL} = {cd.CELERY_BROKER_URL} 

519# Celery max memory per child set to be 

520# celery_max_mem_kilobytes / worker_concurrency (by default number of cpus/cores available) 

521# This example: 4GB / 4 = 1GB = 1000000 

522{ConfigParamExportGeneral.CELERY_WORKER_EXTRA_ARGS} = 

523 --max-tasks-per-child=1000 

524 --max-memory-per-child=100000 

525{ConfigParamExportGeneral.CELERY_EXPORT_TASK_RATE_LIMIT} = 100/m 

526{ConfigParamExportGeneral.EXPORT_LOCKDIR} = {cd.EXPORT_LOCKDIR} 

527 

528{ConfigParamExportGeneral.RECIPIENTS} = 

529 

530{ConfigParamExportGeneral.SCHEDULE_TIMEZONE} = {cd.SCHEDULE_TIMEZONE} 

531{ConfigParamExportGeneral.SCHEDULE} = 

532 

533 

534# ============================================================================= 

535# Details for each export recipient 

536# ============================================================================= 

537 

538# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

539# Example recipient 

540# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

541 # Example (disabled because it's not in the {ConfigParamExportGeneral.RECIPIENTS} list above) 

542 

543[recipient:recipient_A] 

544 

545 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

546 # How to export 

547 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

548 

549{ConfigParamExportRecipient.TRANSMISSION_METHOD} = hl7 

550{ConfigParamExportRecipient.PUSH} = true 

551{ConfigParamExportRecipient.TASK_FORMAT} = pdf 

552{ConfigParamExportRecipient.XML_FIELD_COMMENTS} = {cd.XML_FIELD_COMMENTS} 

553 

554 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

555 # What to export 

556 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

557 

558{ConfigParamExportRecipient.ALL_GROUPS} = false 

559{ConfigParamExportRecipient.GROUPS} = 

560 myfirstgroup 

561 mysecondgroup 

562{ConfigParamExportRecipient.TASKS} = 

563 

564{ConfigParamExportRecipient.START_DATETIME_UTC} = 

565{ConfigParamExportRecipient.END_DATETIME_UTC} = 

566{ConfigParamExportRecipient.FINALIZED_ONLY} = {cd.FINALIZED_ONLY} 

567{ConfigParamExportRecipient.INCLUDE_ANONYMOUS} = {cd.INCLUDE_ANONYMOUS} 

568{ConfigParamExportRecipient.PRIMARY_IDNUM} = 1 

569{ConfigParamExportRecipient.REQUIRE_PRIMARY_IDNUM_MANDATORY_IN_POLICY} = {cd.REQUIRE_PRIMARY_IDNUM_MANDATORY_IN_POLICY} 

570 

571 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

572 # Options applicable to database exports 

573 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

574 

575{ConfigParamExportRecipient.DB_URL} = some_sqlalchemy_url 

576{ConfigParamExportRecipient.DB_ECHO} = {cd.DB_ECHO} 

577{ConfigParamExportRecipient.DB_INCLUDE_BLOBS} = {cd.DB_INCLUDE_BLOBS} 

578{ConfigParamExportRecipient.DB_ADD_SUMMARIES} = {cd.DB_ADD_SUMMARIES} 

579{ConfigParamExportRecipient.DB_PATIENT_ID_PER_ROW} = {cd.DB_PATIENT_ID_PER_ROW} 

580 

581 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

582 # Options applicable to e-mail exports 

583 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

584 

585{ConfigParamExportRecipient.EMAIL_TO} = 

586 Perinatal Psychiatry Admin <perinatal@myinstitution.mydomain> 

587 

588{ConfigParamExportRecipient.EMAIL_CC} = 

589 Dr Alice Bradford <alice.bradford@myinstitution.mydomain> 

590 Dr Charles Dogfoot <charles.dogfoot@myinstitution.mydomain> 

591 

592{ConfigParamExportRecipient.EMAIL_BCC} = 

593 superuser <root@myinstitution.mydomain> 

594 

595{ConfigParamExportRecipient.EMAIL_PATIENT_SPEC_IF_ANONYMOUS} = anonymous 

596{ConfigParamExportRecipient.EMAIL_PATIENT_SPEC} = {{{PatientSpecElementForFilename.SURNAME}}}, {{{PatientSpecElementForFilename.FORENAME}}}, {{{PatientSpecElementForFilename.ALLIDNUMS}}} 

597{ConfigParamExportRecipient.EMAIL_SUBJECT} = CamCOPS task for {{patient}}, created {{created}}: {{tasktype}}, PK {{serverpk}} 

598{ConfigParamExportRecipient.EMAIL_BODY_IS_HTML} = false 

599{ConfigParamExportRecipient.EMAIL_BODY} = 

600 Please find attached a new CamCOPS task for manual filing to the electronic 

601 patient record of 

602 

603 {{patient}} 

604 

605 Task type: {{tasktype}} 

606 Created: {{created}} 

607 CamCOPS server primary key: {{serverpk}} 

608 

609 Yours faithfully, 

610 

611 The CamCOPS computer. 

612 

613{ConfigParamExportRecipient.EMAIL_KEEP_MESSAGE} = {cd.HL7_KEEP_MESSAGE} 

614 

615 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

616 # Options applicable to FHIR 

617 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

618 

619{ConfigParamExportRecipient.FHIR_API_URL} = https://my.fhir.server/api 

620{ConfigParamExportRecipient.FHIR_APP_ID} = {cd.FHIR_APP_ID} 

621{ConfigParamExportRecipient.FHIR_APP_SECRET} = my_fhir_secret_abc 

622{ConfigParamExportRecipient.FHIR_LAUNCH_TOKEN} = 

623{ConfigParamExportRecipient.FHIR_CONCURRENT} = 

624 

625 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

626 # Options applicable to HL7 (v2) exports 

627 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

628 

629{ConfigParamExportRecipient.HL7_HOST} = myhl7server.mydomain 

630{ConfigParamExportRecipient.HL7_PORT} = {cd.HL7_PORT} 

631{ConfigParamExportRecipient.HL7_PING_FIRST} = {cd.HL7_PING_FIRST} 

632{ConfigParamExportRecipient.HL7_NETWORK_TIMEOUT_MS} = {cd.HL7_NETWORK_TIMEOUT_MS} 

633{ConfigParamExportRecipient.HL7_KEEP_MESSAGE} = {cd.HL7_KEEP_MESSAGE} 

634{ConfigParamExportRecipient.HL7_KEEP_REPLY} = {cd.HL7_KEEP_REPLY} 

635{ConfigParamExportRecipient.HL7_DEBUG_DIVERT_TO_FILE} = {cd.HL7_DEBUG_DIVERT_TO_FILE} 

636{ConfigParamExportRecipient.HL7_DEBUG_TREAT_DIVERTED_AS_SENT} = {cd.HL7_DEBUG_TREAT_DIVERTED_AS_SENT} 

637 

638 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

639 # Options applicable to file transfers/attachments 

640 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

641 

642{ConfigParamExportRecipient.FILE_PATIENT_SPEC} = {{surname}}_{{forename}}_{{idshortdesc1}}{{idnum1}} 

643{ConfigParamExportRecipient.FILE_PATIENT_SPEC_IF_ANONYMOUS} = {cd.FILE_PATIENT_SPEC_IF_ANONYMOUS} 

644{ConfigParamExportRecipient.FILE_FILENAME_SPEC} = /my_nfs_mount/mypath/CamCOPS_{{patient}}_{{created}}_{{tasktype}}-{{serverpk}}.{{filetype}} 

645{ConfigParamExportRecipient.FILE_MAKE_DIRECTORY} = {cd.FILE_MAKE_DIRECTORY} 

646{ConfigParamExportRecipient.FILE_OVERWRITE_FILES} = {cd.FILE_OVERWRITE_FILES} 

647{ConfigParamExportRecipient.FILE_EXPORT_RIO_METADATA} = {cd.FILE_EXPORT_RIO_METADATA} 

648{ConfigParamExportRecipient.FILE_SCRIPT_AFTER_EXPORT} = 

649 

650 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

651 # Extra options for RiO metadata for file-based export 

652 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

653 

654{ConfigParamExportRecipient.RIO_IDNUM} = 2 

655{ConfigParamExportRecipient.RIO_UPLOADING_USER} = CamCOPS 

656{ConfigParamExportRecipient.RIO_DOCUMENT_TYPE} = CC 

657 

658 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

659 # Extra options for REDCap export 

660 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

661 

662{ConfigParamExportRecipient.REDCAP_API_URL} = https://domain.of.redcap.server/api/ 

663{ConfigParamExportRecipient.REDCAP_API_KEY} = myapikey 

664{ConfigParamExportRecipient.REDCAP_FIELDMAP_FILENAME} = /location/of/fieldmap.xml 

665 

666# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

667# Example SMS Backends. No configuration needed for '{SmsBackendNames.CONSOLE}' (testing only). 

668# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

669 

670[{CONFIG_FILE_SMS_BACKEND_PREFIX}:{SmsBackendNames.KAPOW}] 

671 

672{KapowSmsBackend.PARAM_USERNAME} = myusername 

673{KapowSmsBackend.PARAM_PASSWORD} = mypassword 

674 

675[{CONFIG_FILE_SMS_BACKEND_PREFIX}:{SmsBackendNames.TWILIO}] 

676 

677{TwilioSmsBackend.PARAM_SID.upper()} = mysid 

678{TwilioSmsBackend.PARAM_TOKEN.upper()} = mytoken 

679{TwilioSmsBackend.PARAM_FROM_PHONE_NUMBER.upper()} = myphonenumber 

680 

681 """.strip() # noqa 

682 

683 

684# ============================================================================= 

685# Demo configuration files, other than the CamCOPS config file itself 

686# ============================================================================= 

687 

688DEFAULT_SOCKET_FILENAME = "/run/camcops/camcops.socket" 

689 

690 

691def get_demo_supervisor_config() -> str: 

692 """ 

693 Returns a demonstration ``supervisord`` config file based on the 

694 specified parameters. 

695 """ 

696 redirect_stderr = "true" 

697 autostart = "true" 

698 autorestart = "true" 

699 startsecs = "30" 

700 stopwaitsecs = "60" 

701 startretries = "10" 

702 stopasgroup = "true" 

703 return f""" 

704# ============================================================================= 

705# Demonstration 'supervisor' (supervisord) config file for CamCOPS. 

706# Created by CamCOPS version {CAMCOPS_SERVER_VERSION_STRING}. 

707# ============================================================================= 

708# See https://camcops.readthedocs.io/en/latest/administrator/server_configuration.html#start-camcops 

709 

710[program:camcops_server] 

711 

712command = {DEFAULT_LINUX_CAMCOPS_EXECUTABLE} serve_gunicorn 

713 --config {DEFAULT_LINUX_CAMCOPS_CONFIG} 

714 

715directory = {DEFAULT_LINUX_CAMCOPS_BASE_DIR} 

716environment = MPLCONFIGDIR="{LINUX_DEFAULT_MATPLOTLIB_CACHE_DIR}" 

717user = {DEFAULT_LINUX_USER} 

718stdout_logfile = {DEFAULT_LINUX_LOGDIR}/camcops_server.log 

719redirect_stderr = {redirect_stderr} 

720autostart = {autostart} 

721autorestart = {autorestart} 

722startsecs = {startsecs} 

723stopwaitsecs = {stopwaitsecs} 

724 

725[program:camcops_workers] 

726 

727command = {DEFAULT_LINUX_CAMCOPS_EXECUTABLE} launch_workers 

728 --config {DEFAULT_LINUX_CAMCOPS_CONFIG} 

729 

730directory = {DEFAULT_LINUX_CAMCOPS_BASE_DIR} 

731environment = MPLCONFIGDIR="{LINUX_DEFAULT_MATPLOTLIB_CACHE_DIR}" 

732user = {DEFAULT_LINUX_USER} 

733stdout_logfile = {DEFAULT_LINUX_LOGDIR}/camcops_workers.log 

734redirect_stderr = {redirect_stderr} 

735autostart = {autostart} 

736autorestart = {autorestart} 

737startsecs = {startsecs} 

738stopwaitsecs = {stopwaitsecs} 

739startretries = {startretries} 

740stopasgroup = {stopasgroup} 

741 

742[program:camcops_scheduler] 

743 

744command = {DEFAULT_LINUX_CAMCOPS_EXECUTABLE} launch_scheduler 

745 --config {DEFAULT_LINUX_CAMCOPS_CONFIG} 

746 

747directory = {DEFAULT_LINUX_CAMCOPS_BASE_DIR} 

748environment = MPLCONFIGDIR="{LINUX_DEFAULT_MATPLOTLIB_CACHE_DIR}" 

749user = {DEFAULT_LINUX_USER} 

750stdout_logfile = {DEFAULT_LINUX_LOGDIR}/camcops_scheduler.log 

751redirect_stderr = {redirect_stderr} 

752autostart = {autostart} 

753autorestart = {autorestart} 

754startsecs = {startsecs} 

755stopwaitsecs = {stopwaitsecs} 

756startretries = {startretries} 

757 

758[group:camcops] 

759 

760programs = camcops_server, camcops_workers, camcops_scheduler 

761 

762 """.strip() # noqa 

763 

764 

765def get_demo_apache_config( 

766 rootpath: str = "", # no slash 

767 specimen_internal_port: int = None, 

768 specimen_socket_file: str = DEFAULT_SOCKET_FILENAME, 

769) -> str: 

770 """ 

771 Returns a demo Apache HTTPD config file section applicable to CamCOPS. 

772 """ 

773 cd = ConfigDefaults() 

774 specimen_internal_port = specimen_internal_port or cd.PORT 

775 indent_8 = " " * 8 

776 

777 if rootpath: 

778 urlbase = f"/{rootpath}" 

779 urlbaseslash = f"{urlbase}/" 

780 api_path = f"{urlbase}{MASTER_ROUTE_CLIENT_API}" 

781 trailing_slash_notes = f"""{indent_8}# 

782 # - Don't specify trailing slashes for the ProxyPass and 

783 # ProxyPassReverse directives. 

784 # If you do, http://camcops.example.com{urlbase} will fail though 

785 # http://camcops.example.com{urlbaseslash} will succeed. 

786 # 

787 # - An alternative fix is to enable mod_rewrite (e.g. sudo a2enmod 

788 # rewrite), then add these commands: 

789 # 

790 # RewriteEngine on 

791 # RewriteRule ^/{rootpath}$ {rootpath}/ [L,R=301] 

792 # 

793 # which will redirect requests without the trailing slash to a 

794 # version with the trailing slash. 

795 #""" 

796 

797 x_script_name = ( 

798 f"{indent_8}RequestHeader set X-Script-Name {urlbase}\n" 

799 ) 

800 else: 

801 urlbase = "/" 

802 urlbaseslash = "/" 

803 api_path = MASTER_ROUTE_CLIENT_API 

804 trailing_slash_notes = " " * 8 + "#" 

805 x_script_name = "" 

806 

807 # noinspection HttpUrlsUsage 

808 return f""" 

809# Demonstration Apache config file section for CamCOPS. 

810# Created by CamCOPS version {CAMCOPS_SERVER_VERSION_STRING}. 

811# 

812# Under Ubuntu, the Apache config will be somewhere in /etc/apache2/ 

813# Under CentOS, the Apache config will be somewhere in /etc/httpd/ 

814# 

815# This section should go within the <VirtualHost> directive for the secure 

816# (SSL, HTTPS) part of the web site. 

817 

818<VirtualHost *:443> 

819 # ... 

820 

821 # ========================================================================= 

822 # CamCOPS 

823 # ========================================================================= 

824 # Apache operates on the principle that the first match wins. So, if we 

825 # want to serve CamCOPS but then override some of its URLs to serve static 

826 # files faster, we define the static stuff first. 

827 

828 # --------------------------------------------------------------------- 

829 # 1. Serve static files 

830 # --------------------------------------------------------------------- 

831 # a) offer them at the appropriate URL 

832 # b) provide permission 

833 # c) disable ProxyPass for static files 

834 

835 # CHANGE THIS: aim the alias at your own institutional logo. 

836 

837 Alias {urlbaseslash}static/logo_local.png {DEFAULT_LINUX_CAMCOPS_STATIC_DIR}/logo_local.png 

838 

839 # We move from more specific to less specific aliases; the first match 

840 # takes precedence. (Apache will warn about conflicting aliases if 

841 # specified in a wrong, less-to-more-specific, order.) 

842 

843 Alias {urlbaseslash}static/ {DEFAULT_LINUX_CAMCOPS_STATIC_DIR}/ 

844 

845 <Directory {DEFAULT_LINUX_CAMCOPS_STATIC_DIR}> 

846 Require all granted 

847 

848 # ... for old Apache versions (e.g. 2.2), use instead: 

849 # Order allow,deny 

850 # Allow from all 

851 </Directory> 

852 

853 # Don't ProxyPass the static files; we'll serve them via Apache. 

854 

855 ProxyPassMatch ^{urlbaseslash}static/ ! 

856 

857 # --------------------------------------------------------------------- 

858 # 2. Proxy requests to the CamCOPS web server and back; allow access 

859 # --------------------------------------------------------------------- 

860 # ... either via an internal TCP/IP port (e.g. 1024 or higher, and NOT 

861 # accessible to users); 

862 # ... or, better, via a Unix socket, e.g. {specimen_socket_file} 

863 # 

864 # NOTES 

865 # 

866 # - When you ProxyPass {urlbase}, you should browse to (e.g.) 

867 # 

868 # https://camcops.example.com{urlbase} 

869 # 

870 # and point your tablet devices to 

871 # 

872 # https://camcops.example.com{api_path} 

873{trailing_slash_notes} 

874 # - Ensure that you put the CORRECT PROTOCOL (http, https) in the rules 

875 # below. 

876 # 

877 # - For ProxyPass options, see https://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass 

878 # 

879 # - Include "retry=0" to stop Apache disabling the connection for 

880 # while on failure. 

881 # - Consider adding a "timeout=<seconds>" option if the back-end is 

882 # slow and causing timeouts. 

883 # 

884 # - CamCOPS MUST BE TOLD about its location and protocol, because that 

885 # information is critical for synthesizing URLs, but is stripped out 

886 # by the reverse proxy system. There are two ways: 

887 # 

888 # (i) specifying headers or WSGI environment variables, such as 

889 # the HTTP(S) headers X-Forwarded-Proto and X-Script-Name below 

890 # (and telling CamCOPS to trust them via its 

891 # TRUSTED_PROXY_HEADERS setting); 

892 # 

893 # (ii) specifying other options to "camcops_server", including 

894 # PROXY_SCRIPT_NAME, PROXY_URL_SCHEME; see the help for the 

895 # CamCOPS config. 

896 # 

897 # So: 

898 # 

899 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

900 # (a) Reverse proxy 

901 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

902 # 

903 # ##################################################################### 

904 # PORT METHOD 

905 # ##################################################################### 

906 # Note the use of "http" (reflecting the backend), not https (like the 

907 # front end). 

908 

909 # ProxyPass {urlbase} http://127.0.0.1:{specimen_internal_port} retry=0 timeout=300 

910 # ProxyPassReverse {urlbase} http://127.0.0.1:{specimen_internal_port} 

911 

912 # ##################################################################### 

913 # UNIX SOCKET METHOD (Apache 2.4.9 and higher) 

914 # ##################################################################### 

915 # This requires Apache 2.4.9, and passes after the '|' character a URL 

916 # that determines the Host: value of the request; see 

917 # ://httpd.apache.org/docs/trunk/mod/mod_proxy.html#proxypass 

918 # 

919 # The general syntax is: 

920 # 

921 # ProxyPass /URL_USER_SEES unix:SOCKETFILE|PROTOCOL://HOST/EXTRA_URL_FOR_BACKEND retry=0 

922 # 

923 # Note that: 

924 # 

925 # - the protocol should be http, not https (Apache deals with the 

926 # HTTPS part and passes HTTP on) 

927 # - the EXTRA_URL_FOR_BACKEND needs to be (a) unique for each 

928 # instance or Apache will use a single worker for multiple 

929 # instances, and (b) blank for the backend's benefit. Since those 

930 # two conflict when there's >1 instance, there's a problem. 

931 # - Normally, HOST is given as localhost. It may be that this problem 

932 # is solved by using a dummy unique value for HOST: 

933 # https://bz.apache.org/bugzilla/show_bug.cgi?id=54101#c1 

934 # 

935 # If your Apache version is too old, you will get the error 

936 # 

937 # "AH00526: Syntax error on line 56 of /etc/apache2/sites-enabled/SOMETHING: 

938 # ProxyPass URL must be absolute!" 

939 # 

940 # If you get this error: 

941 # 

942 # AH01146: Ignoring parameter 'retry=0' for worker 'unix:/tmp/.camcops_gunicorn.sock|https://localhost' because of worker sharing 

943 # https://wiki.apache.org/httpd/ListOfErrors 

944 # 

945 # ... then your URLs are overlapping and should be redone or sorted; 

946 # see http://httpd.apache.org/docs/2.4/mod/mod_proxy.html#workers 

947 # 

948 # The part that must be unique for each instance, with no part a 

949 # leading substring of any other, is THIS_BIT in: 

950 # 

951 # ProxyPass /URL_USER_SEES unix:SOCKETFILE|http://localhost/THIS_BIT retry=0 

952 # 

953 # If you get an error like this: 

954 # 

955 # AH01144: No protocol handler was valid for the URL /SOMEWHERE. If you are using a DSO version of mod_proxy, make sure the proxy submodules are included in the configuration using LoadModule. 

956 # 

957 # Then do this: 

958 # 

959 # sudo a2enmod proxy proxy_http 

960 # sudo apache2ctl restart 

961 # 

962 # If you get an error like this: 

963 # 

964 # ... [proxy_http:error] [pid 32747] (103)Software caused connection abort: [client 109.151.49.173:56898] AH01102: error reading status line from remote server httpd-UDS:0 

965 # [proxy:error] [pid 32747] [client 109.151.49.173:56898] AH00898: Error reading from remote server returned by /camcops_bruhl/webview 

966 # 

967 # then check you are specifying http://, not https://, in the ProxyPass 

968 # 

969 # Other information sources: 

970 # 

971 # - https://emptyhammock.com/projects/info/pyweb/webconfig.html 

972 

973 ProxyPass {urlbase} unix:{specimen_socket_file}|http://dummy1 retry=0 timeout=300 

974 ProxyPassReverse {urlbase} unix:{specimen_socket_file}|http://dummy1 

975 

976 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

977 # (b) Allow proxy over SSL. 

978 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

979 # Without this, you will get errors like: 

980 # ... SSL Proxy requested for wombat:443 but not enabled [Hint: SSLProxyEngine] 

981 # ... failed to enable ssl support for 0.0.0.0:0 (httpd-UDS) 

982 

983 SSLProxyEngine on 

984 

985 <Location {urlbase}> 

986 

987 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

988 # (c) Allow access 

989 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

990 

991 Require all granted 

992 

993 # ... for old Apache versions (e.g. 2.2), use instead: 

994 # 

995 # Order allow,deny 

996 # Allow from all 

997 

998 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

999 # (d) Tell the proxied application that we are using HTTPS, and 

1000 # where the application is installed 

1001 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

1002 # ... https://stackoverflow.com/questions/16042647 

1003 # 

1004 # Enable mod_headers (e.g. "sudo a2enmod headers") and set: 

1005 

1006 RequestHeader set X-Forwarded-Proto https 

1007{x_script_name} 

1008 # ... then ensure the TRUSTED_PROXY_HEADERS setting in the CamCOPS 

1009 # config file includes: 

1010 # 

1011 # HTTP_X_FORWARDED_HOST 

1012 # HTTP_X_FORWARDED_SERVER 

1013 # HTTP_X_FORWARDED_PORT 

1014 # HTTP_X_FORWARDED_PROTO 

1015 # HTTP_X_SCRIPT_NAME 

1016 # 

1017 # (X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Server are 

1018 # supplied by Apache automatically.) 

1019 

1020 </Location> 

1021 

1022 #========================================================================== 

1023 # SSL security (for HTTPS) 

1024 #========================================================================== 

1025 

1026 # You will also need to install your SSL certificate; see the 

1027 # instructions that came with it. You get a certificate by creating a 

1028 # certificate signing request (CSR). You enter some details about your 

1029 # site, and a software tool makes (1) a private key, which you keep 

1030 # utterly private, and (2) a CSR, which you send to a Certificate 

1031 # Authority (CA) for signing. They send back a signed certificate, and 

1032 # a chain of certificates leading from yours to a trusted root CA. 

1033 # 

1034 # You can create your own (a 'snake-oil' certificate), but your tablets 

1035 # and browsers will not trust it, so this is a bad idea. 

1036 # 

1037 # Once you have your certificate: edit and uncomment these lines: 

1038 

1039 # SSLEngine on 

1040 

1041 # SSLCertificateKeyFile /etc/ssl/private/my.private.key 

1042 

1043 # ... a private file that you made before creating the certificate 

1044 # request, and NEVER GAVE TO ANYBODY, and NEVER WILL (or your 

1045 # security is broken and you need a new certificate). 

1046 

1047 # SSLCertificateFile /etc/ssl/certs/my.public.cert 

1048 

1049 # ... signed and supplied to you by the certificate authority (CA), 

1050 # from the public certificate you sent to them. 

1051 

1052 # SSLCertificateChainFile /etc/ssl/certs/my-institution.ca-bundle 

1053 

1054 # ... made from additional certificates in a chain, supplied to you by 

1055 # the CA. For example, mine is univcam.ca-bundle, made with the 

1056 # command: 

1057 # 

1058 # cat TERENASSLCA.crt UTNAddTrustServer_CA.crt AddTrustExternalCARoot.crt > univcam.ca-bundle 

1059 

1060</VirtualHost> 

1061 

1062 """.strip() # noqa 

1063 

1064 

1065# ============================================================================= 

1066# Helper functions 

1067# ============================================================================= 

1068 

1069 

1070def raise_missing(section: str, parameter: str) -> None: 

1071 msg = ( 

1072 f"Config file: missing/blank parameter {parameter} " 

1073 f"in section [{section}]" 

1074 ) 

1075 raise_runtime_error(msg) 

1076 

1077 

1078# ============================================================================= 

1079# CrontabEntry 

1080# ============================================================================= 

1081 

1082 

1083class CrontabEntry(object): 

1084 """ 

1085 Class to represent a ``crontab``-style entry. 

1086 """ 

1087 

1088 def __init__( 

1089 self, 

1090 line: str = None, 

1091 minute: Union[str, int, List[int]] = "*", 

1092 hour: Union[str, int, List[int]] = "*", 

1093 day_of_week: Union[str, int, List[int]] = "*", 

1094 day_of_month: Union[str, int, List[int]] = "*", 

1095 month_of_year: Union[str, int, List[int]] = "*", 

1096 content: str = None, 

1097 ) -> None: 

1098 """ 

1099 Args: 

1100 line: 

1101 line of the form ``m h dow dom moy content content content``. 

1102 minute: 

1103 crontab "minute" entry 

1104 hour: 

1105 crontab "hour" entry 

1106 day_of_week: 

1107 crontab "day_of_week" entry 

1108 day_of_month: 

1109 crontab "day_of_month" entry 

1110 month_of_year: 

1111 crontab "month_of_year" entry 

1112 content: 

1113 crontab "thing to run" entry 

1114 

1115 If ``line`` is specified, it is used. Otherwise, the components are 

1116 used; the default for each of them is ``"*"``, meaning "all". Thus, for 

1117 example, you can specify ``minute="*/5"`` and that is sufficient to 

1118 mean "every 5 minutes". 

1119 """ 

1120 has_line = line is not None 

1121 has_components = bool( 

1122 minute 

1123 and hour 

1124 and day_of_week 

1125 and day_of_month 

1126 and month_of_year 

1127 and content 

1128 ) 

1129 assert ( 

1130 has_line or has_components 

1131 ), "Specify either a crontab line or all the time components" 

1132 if has_line: 

1133 line = line.split("#")[0].strip() # everything before a '#' 

1134 components = line.split() # split on whitespace 

1135 assert ( 

1136 len(components) >= 6 

1137 ), "Must specify 5 time components and then contents" 

1138 ( 

1139 minute, 

1140 hour, 

1141 day_of_week, 

1142 day_of_month, 

1143 month_of_year, 

1144 ) = components[0:5] 

1145 content = " ".join(components[5:]) 

1146 

1147 self.minute = minute 

1148 self.hour = hour 

1149 self.day_of_week = day_of_week 

1150 self.day_of_month = day_of_month 

1151 self.month_of_year = month_of_year 

1152 self.content = content 

1153 

1154 def __repr__(self) -> str: 

1155 return auto_repr(self, sort_attrs=False) 

1156 

1157 def __str__(self) -> str: 

1158 return ( 

1159 f"{self.minute} {self.hour} {self.day_of_week} " 

1160 f"{self.day_of_month} {self.month_of_year} {self.content}" 

1161 ) 

1162 

1163 def get_celery_schedule(self) -> celery.schedules.crontab: 

1164 """ 

1165 Returns the corresponding Celery schedule. 

1166 

1167 Returns: 

1168 a :class:`celery.schedules.crontab` 

1169 

1170 Raises: 

1171 :exc:`celery.schedules.ParseException` if the input can't be parsed 

1172 """ 

1173 return celery.schedules.crontab( 

1174 minute=self.minute, 

1175 hour=self.hour, 

1176 day_of_week=self.day_of_week, 

1177 day_of_month=self.day_of_month, 

1178 month_of_year=self.month_of_year, 

1179 ) 

1180 

1181 

1182# ============================================================================= 

1183# Configuration class. (It gets cached on a per-process basis.) 

1184# ============================================================================= 

1185 

1186 

1187class CamcopsConfig(object): 

1188 """ 

1189 Class representing the CamCOPS configuration. 

1190 """ 

1191 

1192 def __init__(self, config_filename: str, config_text: str = None) -> None: 

1193 """ 

1194 Initialize by reading the config file. 

1195 

1196 Args: 

1197 config_filename: 

1198 Filename of the config file (usual method) 

1199 config_text: 

1200 Text contents of the config file (alternative method for 

1201 special circumstances); overrides ``config_filename`` 

1202 """ 

1203 

1204 def _get_str( 

1205 section: str, 

1206 paramname: str, 

1207 default: str = None, 

1208 replace_empty_strings_with_default: bool = True, 

1209 ) -> Optional[str]: