Deploying Safely Report¶
Note
Please consult technical staff in your organization if you are not familiar with deployment technologies (e.g., Docker).
The deployment method can vary based on available resources and personal preferences, making it impractical to address every detail. Hence, this guide provides:
- General instructions that can be adapted to different deployment environments
- Example of deployment on Render, a cloud platform that is relatively easy to use
General Instructions¶
1. Prepare survey files to use¶
First, make sure you have the following files required for a survey:
- XLSForm file
- Respondent roster file
- Enumerator roster file
Info
If you are not familiar with these files, please review the guide on survey creation.
Then, place these files in a designated location on the host machine (e.g., /survey/files/
),
which will later be mounted to the Docker container.
2. Define environment variables¶
Create .env
file defining the following environment variables:
Name | Description |
---|---|
SAFELY_REPORT_SECRET_KEY |
A key to be used for enhancing the security of the Flask application |
SAFELY_REPORT_ADMIN_PASSWORD |
Password for the admin user |
SAFELY_REPORT_DATABASE_URI |
URI for connecting to a relational database |
XLSFORM_PATH |
Path to the XLSForm file specifying the survey |
RESPONDENT_ROSTER_PATH |
Path to the CSV file containing survey respondent roster |
ENUMERATOR_ROSTER_PATH |
Path to the CSV file containing survey enumerator roster |
Note
XLSFORM_PATH
, RESPONDENT_ROSTER_PATH
, and ENUMERATOR_ROSTER_PATH
should all refer to paths
within the Docker container rather than paths in the host machine. For instance, if the XLSForm
and roster files are mounted to the container's /app/data/
folder, the path variables should all
reference this location (e.g., XLSFORM_PATH=/app/data/xlsform.xlsx
).
3. Start a Docker container¶
Finally, start the Docker container by running:
docker run -d \
-p [HOST-PORT]:80 \
-v [PATH-TO-SURVEY-FILES]:/app/data \
--env-file=[PATH-TO-ENV-FILE] \
princetonddss/safely-report
where
[HOST-PORT]
refers to the port on the host machine to use for the container[PATH-TO-SURVEY-FILES]
refers to the folder on the host machine where XLSForm and roster files are stored[PATH-TO-ENV-FILE]
refers to the.env
file's path on the host machine
Note that the command above is provided as an example — please feel free to update it with any other options (e.g., restart policy).
Example: Deployment on Render¶
Render is a cloud platform that provides relatively easy-to-use web hosting services.
1. Sign up for Render¶
Create a new account here if you do not have one.
2. Deploy Database¶
Follow instructions here to deploy a PostgreSQL database.
3. Deploy Web Application¶
Follow instructions here to deploy Safely Report from the Docker image.
-
Use
docker.io/princetonddss/safely-report
for the image URL. -
Set up a persistent disk following instructions here. Then, follow instructions here to upload XLSForm and roster files to the persistent disk, which makes these files accessible to the application across deploys and restarts.
-
Define environment variables outlined above. For files stored in the persistent disk (e.g., XLSForm), make sure to use the correct mount path in the corresponding environment variables. Follow instructions here to specify the correct database URI.