Skip to content

Commit 4e64437

Browse files
mschoettlemschoettle
authored
docs: improve instructions to deploy (#300)
Update deployment diagrams. Reference deploy-pie.
1 parent 116dd39 commit 4e64437

File tree

4 files changed

+164
-63
lines changed

4 files changed

+164
-63
lines changed

‎docs/install/diagrams/deployment_diagram_pie.puml

Lines changed: 44 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -18,33 +18,23 @@ Deployment_Node(hospital, "Hospital", "Hospital Network") {
1818
Deployment_Node(opal, "Opal PIE", "Hospital data centre") {
1919
Deployment_Node(apps, "Application Server", "CentOS Stream9 or Ubuntu LTS") {
2020
Deployment_Node(apps_runtime, "Container Runtime", "Docker Engine") {
21-
Container(traefik, "Reverse Proxy", "traefik", "Takes care of TLS termination and path rewrites\nRedirects all HTTP to HTTPS")
22-
Container(backend, "Backend", "", "Web application exposing APIs and providing new OpalAdmin interface")
23-
Container(opaladmin, "Opal Admin", "Apache, PHP", "Web application for clinicians and staff to set up and manage data")
21+
Container(traefik, "Reverse Proxy", "traefik", "Takes care of TLS termination and path rewrites\nRedirects all HTTP requests to HTTPS")
22+
Container(admin, "Opal Admin", "", "Web application exposing APIs and providing new OpalAdmin interface")
23+
Container(admin_legacy, "Opal Admin Legacy", "Apache, PHP", "Web application for clinicians and staff to set up and manage data")
2424
Container(listener, "Listener", "Node.js", "Handles requests from the user applications to access patient data")
25-
Container(labs, "opal-labs", "Apache, PHP", "Responsible for retrieving lab result history via VSign-WS")
26-
Container(orms, "ORMS", "Apache, PHP", "Opal Room Management Software that provides the virtual waiting room and live clinician dashboard")
27-
Container(pdfgen, "PDF Generator", "Apache, PHP", "Generates PDFs for questionnaires")
28-
Container(memcached, "Memcached", "", "Stores user sessions")
29-
Container(highcharts, "Highcharts Export Server", "", "Generates images of charts")
30-
Container(redis, "redis", "", "Caches patients being processed to avoid sending push notifications when batch processing")
31-
Container(alembic, "alembic", "", "Database migrations\nRun at initialization or upgrade time to migrate DBs", $tags="init")
25+
' Container(orms, "ORMS", "Apache, PHP", "Opal Room Management Software that provides the virtual waiting room and live clinician dashboard")
26+
Container(redis, "redis", "", "Caches patients being processed to avoid sending push notifications when batch processing lab results")
27+
Container(db_management, "db-management", "", "Database migrations\nRun at initialization or upgrade time to migrate DBs", $tags="init")
28+
Container(ofelia, "ofelia", "", "Sidecar to run tasks periodically on containers")
29+
Container_Boundary(db, "MariaDB", "MariaDB") {
30+
ContainerDb(legacy_dbs, "Legacy Databases", "RDS", "DBs for legacy components\n(OpalDB, QuestionnaireDB)")
31+
ContainerDb(admin_db, "Backend Database", "RDS", "DB for admin")
32+
33+
}
3234
}
3335
}
3436

35-
Deployment_Node(dbs, "Database Server", "CentOS Stream9 or Ubuntu LTS") {
36-
Deployment_Node(db, "MariaDB", "MariaDB") {
37-
ContainerDb(legacy_dbs, "Legacy Databases", "RDS", "DB(s) for legacy components")
38-
ContainerDb(backend_db, "Backend Database", "RDS", "DB for backend")
39-
}
40-
}
41-
Deployment_Node(integration, "Integration Server", "CentOS Stream9 or Ubuntu LTS") {
42-
Deployment_Node(integration_runtime, "Container Runtime", "Docker Engine") {
43-
Container(mirth, "Integration Engine", "Mirth Connect", "Interfaces with hospital source systems")
44-
Container(nginx, "Reverse Proxy", "nginx", "Takes care of TLS termination and forwards paths to APIs exposed on integration engine ports")
45-
ContainerDb(oie_dbs, "OIE Databases", "RDS", "DB(s) for Mirth and integration engine specifics")
46-
}
47-
}
37+
Container_Ext(integration_engine, "Integration Engine", "", "Interfaces with source systems\nExposes API endpoints")
4838
}
4939
}
5040

@@ -53,49 +43,44 @@ Deployment_Node(firebase, "Firebase") {
5343

5444
}
5545

56-
Container_Ext(rtd_orms, "Realtime Database", "us-central1", "Temporarily stores shortened patient names to call patients via TV screens in the waiting rooms") {
57-
58-
}
46+
' Container_Ext(rtd_orms, "Realtime Database", "us-central1", "Temporarily stores shortened patient names to call patients via TV screens in the waiting rooms") {
47+
'
48+
' }
5949
}
6050

6151
Rel(browser, traefik, "Makes request\nvia browser", "HTTP/HTTPS")
62-
Rel(traefik, backend, "Sends requests to / to")
63-
Rel(traefik, opaladmin, "Sends requests to /opalAdmin to")
64-
Rel(traefik, labs, "Sends requests to /opal-labs to")
65-
Rel(traefik, orms, "Sends requests to /orms to")
66-
67-
Rel(nginx, mirth, "Forwards requests to", "HTTP")
68-
Rel(mirth, oie_dbs, "Reads from and writes to")
69-
Rel(mirth, backend, "Makes API calls to", "HTTPS")
70-
Rel(mirth, opaladmin, "Makes API calls to", "HTTPS")
71-
Rel(mirth, labs, "Makes API calls to", "HTTPS")
72-
Rel(mirth, orms, "Makes API calls to", "HTTPS")
73-
74-
Rel(backend, nginx, "Makes API calls to", "HTTPS")
75-
Rel(listener, nginx, "Makes API calls to", "HTTPS")
76-
Rel(opaladmin, nginx, "Makes API calls to", "HTTPS")
77-
Rel(orms, nginx, "Makes API calls to", "HTTPS")
78-
79-
' Rel(backend, pdfgen, "Makes API calls to", "HTTP")
80-
Rel(pdfgen, highcharts, "Makes API calls to", "HTTP")
81-
Rel(labs, redis, "Makes calls to")
82-
Rel(orms, memcached, "Makes calls to")
83-
84-
Rel(backend, backend_db, "Reads from and writes to", "TLS")
85-
Rel(backend, legacy_dbs, "Reads from and writes to", "TLS")
86-
Rel(opaladmin, legacy_dbs, "Reads from and writes to", "TLS")
87-
Rel(labs, legacy_dbs, "Reads from and writes to", "TLS")
88-
Rel(listener, legacy_dbs, "Reads from and writes to", "TLS")
89-
Rel(orms, legacy_dbs, "Reads from and writes to", "TLS")
90-
Rel(pdfgen, legacy_dbs, "Reads from and writes to", "TLS")
91-
Rel(alembic, legacy_dbs, "Reads from and writes to", "TLS", $tags="init")
52+
Rel(traefik, admin, "Sends requests to / to")
53+
Rel(traefik, admin_legacy, "Sends requests to /opalAdmin to")
54+
' Rel(traefik, orms, "Sends requests to /orms to")
55+
56+
Rel(integration_engine, traefik, "Makes API calls to", "HTTPS")
57+
'Rel(integration_engine, admin_legacy, "Makes API calls to", "HTTPS")
58+
'Rel(integration_engine, orms, "Makes API calls to", "HTTPS")
59+
60+
Rel(admin, integration_engine, "Makes API calls to", "HTTPS")
61+
Rel(listener, integration_engine, "Makes API calls to", "HTTPS")
62+
Rel(admin_legacy, integration_engine, "Makes API calls to", "HTTPS")
63+
'Rel(orms, integration_engine, "Makes API calls to", "HTTPS")
64+
65+
Rel(admin_legacy, redis, "Makes calls to")
66+
' Rel(orms, memcached, "Makes calls to")
67+
68+
Rel(admin, admin_db, "Reads from and writes to", "")
69+
Rel(admin, legacy_dbs, "Reads from and writes to", "")
70+
Rel(admin_legacy, legacy_dbs, "Reads from and writes to", "")
71+
Rel(listener, legacy_dbs, "Reads from and writes to", "")
72+
' Rel(orms, legacy_dbs, "Reads from and writes to", "")
73+
Rel(db_management, legacy_dbs, "Reads from and writes to", "", $tags="init")
9274

9375
Rel(listener, rtd_opal, "Connects to, reads from, and writes to")
94-
Rel(orms, rtd_orms, "Connects to, reads from, and writes to")
76+
' Rel(orms, rtd_orms, "Connects to, reads from, and writes to")
77+
78+
Lay_Left(admin_legacy, admin)
79+
Lay_Up(redis, db)
9580

96-
LAYOUT_WITH_LEGEND()
81+
' LAYOUT_WITH_LEGEND()
9782
SHOW_LEGEND()
9883

99-
footer drawn with PlantUML version %version() and C4-PlantUML version C4Version()
84+
footer Relationships between components on the same host are left out for brevity (except those making use of third-party components).\n\ndrawn with PlantUML version %version() and C4-PlantUML version C4Version()
10085

10186
@enduml

‎docs/install/diagrams/deployment_diagram_pie_db.puml

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
' SPDX-FileCopyrightText: Copyright (C) 2024 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <[email protected]>
2+
'
3+
' SPDX-License-Identifier: CC-BY-SA-4.0
4+
5+
@startuml Opal PIE Deployment
6+
!include <C4/C4_Deployment>
7+
8+
title Deployment diagram for the Opal PIE with a separate database server
9+
10+
AddElementTag("init", $bgColor="#c0c0c0", $legendText="init (used at deploy or upgrade time)")
11+
AddRelTag("init", $textColor="#c0c0c0", $lineColor="#c0c0c0")
12+
13+
Deployment_Node(hospital, "Hospital", "Hospital Network") {
14+
Deployment_Node(browser, "Browser", "Firefox, Chrome, or Edge", "Clinical staff use a browser to access the web applications") {
15+
16+
}
17+
18+
Deployment_Node(opal, "Opal PIE", "Hospital data centre") {
19+
Deployment_Node(apps, "Application Server", "CentOS Stream9 or Ubuntu LTS") {
20+
Deployment_Node(apps_runtime, "Container Runtime", "Docker Engine") {
21+
Container(traefik, "Reverse Proxy", "traefik", "Takes care of TLS termination and path rewrites\nRedirects all HTTP requests to HTTPS")
22+
Container(admin, "Opal Admin", "", "Web application exposing APIs and providing new OpalAdmin interface")
23+
Container(admin_legacy, "Opal Admin Legacy", "Apache, PHP", "Web application for clinicians and staff to set up and manage data")
24+
Container(listener, "Listener", "Node.js", "Handles requests from the user applications to access patient data")
25+
' Container(orms, "ORMS", "Apache, PHP", "Opal Room Management Software that provides the virtual waiting room and live clinician dashboard")
26+
Container(redis, "redis", "", "Caches patients being processed to avoid sending push notifications when batch processing lab results")
27+
Container(db_management, "db-management", "", "Database migrations\nRun at initialization or upgrade time to migrate DBs", $tags="init")
28+
Container(ofelia, "ofelia", "", "Sidecar to run tasks periodically on containers")
29+
}
30+
}
31+
Deployment_Node(dbs, "Application Server", "CentOS Stream9 or Ubuntu LTS") {
32+
Deployment_Node(db, "MariaDB", "MariaDB") {
33+
ContainerDb(legacy_dbs, "Legacy Databases", "RDS", "DBs for legacy components\n(OpalDB, QuestionnaireDB)")
34+
ContainerDb(admin_db, "Backend Database", "RDS", "DB for admin")
35+
36+
}
37+
}
38+
39+
Container_Ext(integration_engine, "Integration Engine", "", "Interfaces with source systems\nExposes API endpoints")
40+
}
41+
}
42+
43+
Deployment_Node(firebase, "Firebase") {
44+
Container_Ext(rtd_opal, "Realtime Database", "us-central1", "Temporarily stores requests and responses from the user applications") {
45+
46+
}
47+
48+
' Container_Ext(rtd_orms, "Realtime Database", "us-central1", "Temporarily stores shortened patient names to call patients via TV screens in the waiting rooms") {
49+
'
50+
' }
51+
}
52+
53+
Rel(browser, traefik, "Makes request\nvia browser", "HTTP/HTTPS")
54+
Rel(traefik, admin, "Sends requests to / to")
55+
Rel(traefik, admin_legacy, "Sends requests to /opalAdmin to")
56+
' Rel(traefik, orms, "Sends requests to /orms to")
57+
58+
Rel(integration_engine, traefik, "Makes API calls to", "HTTPS")
59+
'Rel(integration_engine, admin_legacy, "Makes API calls to", "HTTPS")
60+
'Rel(integration_engine, orms, "Makes API calls to", "HTTPS")
61+
62+
Rel(admin, integration_engine, "Makes API calls to", "HTTPS")
63+
Rel(listener, integration_engine, "Makes API calls to", "HTTPS")
64+
Rel(admin_legacy, integration_engine, "Makes API calls to", "HTTPS")
65+
'Rel(orms, integration_engine, "Makes API calls to", "HTTPS")
66+
67+
Rel(admin_legacy, redis, "Makes calls to")
68+
' Rel(orms, memcached, "Makes calls to")
69+
70+
Rel(admin, admin_db, "Reads from and writes to", "TLS")
71+
Rel(admin, legacy_dbs, "Reads from and writes to", "TLS")
72+
Rel(admin_legacy, legacy_dbs, "Reads from and writes to", "TLS")
73+
Rel(listener, legacy_dbs, "Reads from and writes to", "TLS")
74+
' Rel(orms, legacy_dbs, "Reads from and writes to", "")
75+
Rel(db_management, legacy_dbs, "Reads from and writes to", "TLS", $tags="init")
76+
77+
Rel(listener, rtd_opal, "Connects to, reads from, and writes to")
78+
' Rel(orms, rtd_orms, "Connects to, reads from, and writes to")
79+
80+
Lay_Left(admin_legacy, admin)
81+
Lay_Up(redis, db)
82+
83+
' LAYOUT_WITH_LEGEND()
84+
SHOW_LEGEND()
85+
86+
footer Relationships between components on the same host are left out for brevity (except those making use of third-party components).\n\ndrawn with PlantUML version %version() and C4-PlantUML version C4Version()
87+
88+
@enduml

‎docs/install/diagrams/deployment_diagram_user.puml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Deployment_Node(browser, "User browser", "Firefox, Chrome, Edge etc.") {
1616
Container(registration_spa, "User Registration", "Single Page Application")
1717
}
1818

19-
Deployment_Node(hosting, "Web Hosting", "Shared web hosting") {
19+
Deployment_Node(hosting, "Web Hosting", "") {
2020
Deployment_Node(apache, "Web Server", "Apache") {
2121
Container(webapp, "Web app", "", "Delivers the static content and the web app single page application")
2222
Container(registration, "User Registration", "", "Delivers the static content and the registration single page application")

‎docs/install/index.md

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,46 @@ SPDX-License-Identifier: CC-BY-SA-4.0
66

77
# Deploying the Opal solution
88

9-
The Opal PIE is typically deployed in a hospital and only accessible within the hospital's network.
10-
The user applications are deployed and maintained by the Opal Health Informatics Group (O-HIG).
9+
## High-level Architecture
10+
11+
<figure markdown="span">
12+
![Opal High-Level Architecture](https://raw.githubusercontent.com/opalmedapps/.github/refs/heads/main/profile/architecture.png){ width=500 }
13+
</figure>
14+
15+
The platform's primary goal is to securely share data across the perimeter of a healthcare institution's protected network between the Opal app and their medical record in the hospital's source systems.
16+
This is achieved using a cloud-hosted authentication service and *Realtime Database* relay.
17+
Currently, this service is provided by Google's [Firebase](https://firebase.google.com/) service.
18+
19+
The Opal PIE is typically deployed in a hospital (but does not have to be).
20+
The user applications are deployed separately, on a web server and the mobile app stores.
1121

1222
## Deploying the Opal PIE
1323

14-
### Deployment diagram
24+
### Deployment diagrams
25+
26+
We support different deployment scenarios for how the database is deployed.
27+
28+
For ease of deployment (such as when testing a deployment) you can deploy the database as a container:
1529

1630
```plantuml source="docs/install/diagrams/deployment_diagram_pie.puml"
1731
```
1832

1933
Relationships between components on the same host are left out for brevity (except those making use of third-party components).
2034

35+
The database server can also be run on a separate server:
36+
37+
```plantuml source="docs/install/diagrams/deployment_diagram_pie_db.puml"
38+
```
39+
40+
Relationships between components on the same host are left out for brevity (except those making use of third-party components).
41+
42+
### Automated deployment
43+
44+
We offer a semi-automated deployment via a [`copier`](https://copier.readthedocs.io/en/stable/) template.
45+
This project template supports various deployment options and sets up the basic project structure to get the Opal PIE deployed in a few minutes.
46+
47+
Please follow the instructions in the [`deploy-pie`](https://github.com/opalmedapps/deploy-pie) repository.
48+
2149
## User Applications
2250

2351
### Deployment diagram

0 commit comments

Comments
 (0)