Skip to content

Commit 4b623ad

Browse files
bjubesbjubes
committed
combine documentation
1 parent 21d86a3 commit 4b623ad

File tree

2 files changed

+171
-183
lines changed

2 files changed

+171
-183
lines changed

‎docs/getting-started/justin-production.rst

-159
This file was deleted.

‎docs/getting-started/production.rst

+171-24
Original file line numberDiff line numberDiff line change
@@ -7,24 +7,61 @@ Building Production Containers
77

88
The production containers of Osler are slightly different than their development counterparts, and require a few extra steps to run. It is recommended to remove the local containers before continuing to prevent conflicts or confusion. This guide will use the generic production.yml docker-compose stack, but it is recommend to copy and customize it to your use case.
99

10-
#. Install Docker_ per the Docker instructions for your platform.
10+
Install Docker per the Docker instructions for your platform.
11+
--------------------------------------------------------------
1112

12-
#. Download the `latest release of Osler <https://github.com/oslerproject/osler/releases/latest>`_ either with git:
1313

14-
.. code-block:: console
14+
Download the `latest release of Osler <https://github.com/oslerproject/osler/releases/latest>`_
15+
-----------------------------------------------------------------------------------------------------------------
16+
Via git:
1517

16-
$ git clone https://github.com/oslerproject/osler.git
17-
$ git checkout v2.1.0
18+
.. code-block:: console
1819
19-
or as a zip:
20+
$ git clone https://github.com/oslerproject/osler.git
21+
$ git checkout v2.1.0
2022
21-
.. code-block:: console
23+
As a zip:
2224

23-
$ wget https://github.com/oslerproject/osler/archive/v2.1.0.tar.gz
24-
$ tar -xvzf v2.1.0.tar.gz
25+
.. code-block:: console
2526
26-
#. Create the :code:`.secrets` file:
27-
This file contains sensitive information about the Osler instance that would allow break confidentailty if exposed. As such, it must be created manually for each unique Osler instance. The file must be placed in :code:`osler/.envs/.production/.secrets`.
27+
$ wget https://github.com/oslerproject/osler/archive/v2.1.0.tar.gz
28+
$ tar -xvzf v2.1.0.tar.gz
29+
30+
Set up a docker compose file
31+
----------------------------
32+
33+
The global configuration of your docker containers is set up in `production.yml`.
34+
We have a number of examples, including the demo (`production-demo.yml`). These set up
35+
virtual machines for each of the elements of the web app.
36+
37+
The Database
38+
------------
39+
40+
We use PostgresQL. The database container is named `postgres`. Here is an example of a configuration:
41+
42+
.. code-block:: yaml
43+
44+
postgres:
45+
build:
46+
context: .
47+
dockerfile: ./compose/production/postgres/Dockerfile
48+
image: llemr_production_postgres
49+
container_name: postgres
50+
volumes:
51+
- production_postgres_data:/var/lib/postgresql/data
52+
- production_postgres_data_backups:/backups
53+
env_file:
54+
- ./.envs/.production/.postgres
55+
- ./.envs/.secrets/.postgres
56+
networks:
57+
- database_network
58+
59+
The key here is the `env_file` section, which sets some important environment variables. the file `./.envs/.secrets/.postgres` *does not exist*, and must be created. Create a file that looks something like:
60+
61+
62+
Create the :code:`.secrets` file:
63+
----------------------------------
64+
This file contains sensitive information about the Osler instance that would allow break confidentailty if exposed. As such, it must be created manually for each unique Osler instance. It should never be check into git, and is ignored by git by default. The file must be placed in :code:`osler/.envs/.production/.secrets`.
2865
The file should contain database credentials and the django secret key. **Do not use the values below. They are only an example**
2966

3067
.. code-block::
@@ -42,22 +79,132 @@ The production containers of Osler are slightly different than their development
4279
# ------------------------------------------------------------------------------
4380
DJANGO_SECRET_KEY=PbQjPuCXmpX4dHJITSI2nSJy6lzivrHkyxIZJkAnowUsEzsWkucovzd75yz8BqVH
4481
45-
#. Generate or install TLS keys:
46-
In production, Osler should always be accessed exclusivly with HTTPS for security reasons. In the production compose stack, nginx automatically serves Osler using HTTPS with the SSL certificates at `osler/compose/production/certs/`. If you are using certificates issued by a third party, place them in this directory, ensuring the following permissions
47-
.. code-block::
48-
-rw-r--r-- cert.crt
49-
-rw------- cert.key
50-
Alternatively, you can generate your own certificates for nginx to use. Because these will be self-signed, they will cause all web browers to display a certificate warning the first time vising the site.
51-
To generate certificates, run this from the root directory of Osler:
5282
53-
.. code-block:: console
83+
The Web App
84+
-----------
85+
86+
The web app is run with gunicorn in a custom Dockerfile. This guy accounts for by far the majority of the runtime of `docker-compose build`.
87+
88+
.. note::
89+
We provide the postgres configuration environment files
90+
(`.envs/.production/.postgres` and `./.envs/.secrets/.postgres`) to _both_
91+
the django container and the postgres container. This is because the
92+
django container needs to be able to connect and authenticate to the
93+
postgres container!
94+
95+
.. code-block:: yaml
96+
97+
django:
98+
build:
99+
context: .
100+
dockerfile: ./compose/production/django/Dockerfile
101+
image: llemr_production_django
102+
container_name: django
103+
ports:
104+
- 5000:5000
105+
depends_on:
106+
- postgres
107+
- redis
108+
environment:
109+
- DJANGO_SETTINGS_MODULE=config.settings.production-demo
110+
env_file:
111+
- ./.envs/.production/.django
112+
- ./.envs/.production/.postgres
113+
- ./.envs/.secrets/.postgres
114+
- ./.envs/.secrets/.django
115+
command: /start
116+
networks:
117+
- nginx_network
118+
- database_network
119+
120+
Notice that we use the `environment` section to provide `DJANGO_SETTINGS_MODULE`, which points to `config/settings/production-demo.py`. This file contains:
121+
122+
.. code-block:: python
123+
124+
from .production import *
125+
from .demo import *
126+
127+
Thus, it combines the configurations listed in `config/settings/production.py` and `config/settings/demo.py`, with those in `demo.py` overriding anything in `production.py` (since `demo.py` comes second). Most of the settings in `production.py` are strong recommendations for production, whereas those in `demo.py` are likely to be configured by you.
128+
129+
.. code-block:: python
130+
from .base import env
131+
132+
TIME_ZONE = "America/Chicago"
133+
LANGUAGE_CODE = "en-us"
134+
135+
OSLER_ROLE_DASHBOARDS = {
136+
'Attending': 'dashboard-attending',
137+
'Physician': 'dashboard-attending',
138+
}
139+
140+
OSLER_DISPLAY_REFERRALS = False
141+
OSLER_DISPLAY_APPOINTMENTS = False
142+
OSLER_DISPLAY_CASE_MANAGERS = False
143+
OSLER_DISPLAY_ATTESTABLE_BASIC_NOTE = False
144+
OSLER_DISPLAY_DIAGNOSIS = False
145+
OSLER_DISPLAY_VOUCHERS = False
146+
OSLER_DISPLAY_WILL_RETURN = False
147+
OSLER_DISPLAY_ATTENDANCE = True
148+
OSLER_DISPLAY_FOLLOWUP = False
149+
OSLER_DISPLAY_VACCINE = False
150+
151+
OSLER_DEFAULT_CITY = "Gotham"
152+
OSLER_DEFAULT_STATE = "New Jersey"
153+
OSLER_DEFAULT_ZIP_CODE = "00000"
154+
OSLER_DEFAULT_COUNTRY = "USA"
155+
OSLER_DEFAULT_ADDRESS = ""
156+
157+
OSLER_ABOUT_NAME = "About"
158+
OSLER_ABOUT_URL = "https://llemrconspiracy.org"
159+
160+
161+
The Web Server
162+
--------------
163+
164+
The web server we use is nginx. It's responsible for serving static files, terminating SSL, and passing data to gunicorn. The pertinent part of the docker compose file is here:
165+
166+
.. code-block:: yaml
167+
168+
nginx:
169+
image: nginx:1.19
170+
container_name: nginx
171+
ports:
172+
- 80:80
173+
- 443:443
174+
env_file:
175+
- ./.envs/.production/.nginx
176+
volumes:
177+
- ./compose/production/nginx/templates:/etc/nginx/templates
178+
- ./compose/production/nginx/certs:/etc/nginx/certs
179+
depends_on:
180+
- django
181+
networks:
182+
- nginx_network
183+
184+
185+
Generate or install TLS keys:
186+
--------------------------------
187+
In production, Osler should always be accessed exclusivly with HTTPS for security reasons. In the production compose stack, nginx automatically serves Osler using HTTPS with the SSL certificates at `osler/compose/production/certs/`. If you are using certificates issued by a third party, place them in this directory, ensuring the following permissions
188+
189+
.. code-block::
190+
191+
-rw-r--r-- cert.crt
192+
-rw------- cert.key
193+
194+
Alternatively, you can generate your own certificates for nginx to use. Because these will be self-signed, they will cause all web browers to display a certificate warning the first time vising the site.
195+
To generate certificates, run this from the root directory of Osler:
196+
197+
.. code-block:: console
198+
199+
openssl req -x509 -sha256 -nodes -newkey rsa:2048 -days 365 -keyout ./compose/production/nginx/certs/cert.key -out ./compose/production/nginx/certs/cert.crt
54200
55-
openssl req -x509 -sha256 -nodes -newkey rsa:2048 -days 365 -keyout ./compose/production/nginx/certs/cert.key -out ./compose/production/nginx/certs/cert.crt
201+
Build and run the docker containers
202+
------------------------------------
203+
This could take a while. Note: if you redo any previous steps, rerun this command with the :code:`--build` argument.
56204

57-
#. Build and run the docker containers (this could take a while). Note: if you redo any previous steps, rerun this command with the :code:`--build` argument.
58-
.. code-block:: console
205+
.. code-block:: console
59206
60-
$ docker-compose -f production.yml up
207+
$ docker-compose -f production.yml up
61208
62209
63-
#. Check everything is working by visiting https://localhost in your browser.
210+
Check everything is working by visiting https://localhost in your browser.

0 commit comments

Comments
 (0)