|
| 1 | +# SafePlaces Translation Service |
1 | 2 |
|
2 | | -# Safeplaces Backend Translation Example |
| 3 | +The SafePlaces Translation Service is a private standalone API that is utilized by the SafePlaces Frontend to create, delete, update, and query for GPS points associated with a case or set of cases. |
3 | 4 |
|
4 | | -This repository holds an example backend for translation endpoints for the [Safeplaces Translation API specification](https://github.com/Path-Check/safeplaces-backend-translation/blob/dev/openapi.yaml). |
5 | | - |
6 | | -Safeplaces is a toolkit for public health, built on top of data shared by users of [Private Kit](https://github.com/tripleblindmarket/covid-safe-paths). |
7 | | - |
8 | | -[Safeplaces Frontend](https://github.com/Path-Check/safeplaces-frontend) is an example client for these backends. |
9 | | - |
10 | | -## Project Status |
11 | | - |
12 | | -[](https://www.repostatus.org/#wip) |
13 | | - |
14 | | -The project is still under development and will reach a Minimum Viable Product (MVP) stage soon. |
15 | | -*Note*: There can be breaking changes to the developing code until the MVP is released. |
16 | | - |
17 | | -## Publishing Files |
18 | | - |
19 | | -Files can be published to either Google Cloud Storage (GCS) or AWS Simple Storage Service (S3). This preference is set via an environment variable. If not set, tests will default to local storage (write to disk) to pass. This variable is required in a production environment. |
20 | | - |
21 | | -``` |
22 | | -PUBLISH_STORAGE_TYPE=(gcs|aws) |
23 | | -``` |
24 | | - |
25 | | -## Google Cloud Storage (GCS) |
26 | | - |
27 | | -The following environment variables are required: |
28 | | - |
29 | | -``` |
30 | | -GOOGLE_APPLICATION_CREDENTIALS='google_service_account.json' |
31 | | -GOOGLE_CLOUD_PROJECT=something |
32 | | -GCLOUD_STORAGE_BUCKET=somethingOrOther |
33 | | -``` |
34 | | - |
35 | | -## AWS Simple Storage Service (S3) |
36 | | - |
37 | | -The following environment variables are required: |
38 | | - |
39 | | -``` |
40 | | -S3_BUCKET=bucket-name |
41 | | -S3_REGION=region-name |
42 | | -S3_ACCESS_KEY=something |
43 | | -S3_SECRET_KEY=something-secret |
44 | | -``` |
45 | | - |
46 | | -## Deployment |
47 | | - |
48 | | -### Deploy in local machine |
49 | | - |
50 | | -*Note*: |
51 | | -1. The installation assumes you have already installed Postgres DB in your local environment listening for connections at port 5432. |
52 | | -2. Your Postgres instance should listen to '*' instead of 'localhost' by setting the `listen_addresses` parameter, [this setting can be found in your pgconfig file](https://www.postgresql.org/docs/current/runtime-config-connection.html). |
53 | | - |
54 | | -Clone this repository |
55 | | - |
56 | | -``` |
57 | | -cd safeplaces-backend/expressjs |
58 | | -``` |
59 | | - |
60 | | -#### Install Package Manager |
61 | | - |
62 | | -Steps to install NVM are documented [in the nvm repository](https://github.com/nvm-sh/nvm#installing-and-updating). |
63 | | - |
64 | | -Install npm using nvm |
65 | | - |
66 | | -``` |
67 | | -nvm install 13.1.0 |
68 | | -nvm use 13.1.0 |
69 | | -npm install |
70 | | -``` |
71 | | - |
72 | | -#### Setup Environment |
73 | | - |
74 | | -Refer [.env.template](.env.template) for environment variables to be exported to your environment. |
75 | | - |
76 | | -#### Setup LDAP Server |
77 | | -The basic, included LDAP server is to be used for testing purposes only. |
78 | | -It is not meant for production use. |
79 | | - |
80 | | -Please see the OpenLDAP implementations for production-ready servers. Once set up, modify the environment |
81 | | -variables to point to the new server, with the proper host, port, password, domain components, and bind command. |
82 | | - |
83 | | -Example: |
84 | | -``` |
85 | | -LDAP_HOST=localhost |
86 | | -LDAP_PORT=1389 |
87 | | -LDAP_PASS=safepaths |
88 | | -LDAP_ORG="dc=covidsafepaths, dc=org" |
89 | | -LDAP_BIND="cn=admin, dc=covidsafepaths, dc=org" |
90 | | -LDAP_SEARCH="cn={{username}}, dc=covidsafepaths, dc=org" |
91 | | -LDAP_FILTER="(objectClass=*)" |
92 | | -``` |
93 | | - |
94 | | -The Express server queries the LDAP server with each login request at `/login`. |
95 | | - |
96 | | -The search query will look like |
97 | | -`cn={{username}}, dc=covidsafepaths, dc=org` |
98 | | - |
99 | | -Note that `{{username}}` is **explicitly required.** |
100 | | -`{{username}}` will be replaced by the username sent by the client's request. |
101 | | - |
102 | | -To run the server: |
103 | | -``` |
104 | | -cd ldapjs/ |
105 | | -npm install |
106 | | -npm start |
107 | | -``` |
108 | | - |
109 | | -#### Setup Database |
110 | | - |
111 | | -1. Create databases and users mentioned exported in your environment. |
112 | | -1. Grant database user superuser privilege to the database to create POSTGIS extension and setup other tables. Reduce this privilege later to just create and modify tables or tuples in this database after you run the migration for the first time. |
113 | | -1. Install [PostGIS extension](https://postgis.net/install/). |
114 | | - |
115 | | -#### Knex migrations and seed the database |
116 | | - |
117 | | -Install Knex globally |
118 | | - |
119 | | -``` |
120 | | -npm install knex -g |
121 | | -``` |
122 | | - |
123 | | -Run migrations |
124 | | - |
125 | | -``` |
126 | | -knex migrate:latest --env test |
127 | | -knex migrate:latest --env development |
128 | | -``` |
129 | | - |
130 | | -Seed the database |
131 | | - |
132 | | -``` |
133 | | -knex seed:run --env test |
134 | | -knex seed:run --env development |
135 | | -``` |
136 | | - |
137 | | -#### Mocha unit tests |
138 | | - |
139 | | -Install mocha globally. |
140 | | - |
141 | | -``` |
142 | | -npm install mocha -g |
143 | | -``` |
144 | | - |
145 | | -Run testing through mocha to see if unit tests pass |
146 | | - |
147 | | -``` |
148 | | -mocha |
149 | | -``` |
150 | | - |
151 | | -### Deploy using Docker |
152 | | - |
153 | | -*Note*: |
154 | | -1. The installation assumes you have already installed Postgres DB in your local environment listening for connections at port 5432. |
155 | | -2. Your Postgres instance should listen to '*' instead of 'localhost' by setting the `listen_addresses` parameter, [this setting can be found in your pgconfig file](https://www.postgresql.org/docs/current/runtime-config-connection.html). |
156 | | -3. Your `pg_hba.conf` should have a rule added for `host all all <docker-subnet> md5`. Replace `<docker-subnet>` with the actual CIDR for your docker installation's subnet. Note that `172.18.0.0/16` is usually the default. |
157 | | - |
158 | | -Clone this repository |
159 | | - |
160 | | -``` |
161 | | -cd safeplaces-backend/expressjs |
162 | | -``` |
163 | | - |
164 | | -#### Build Dockerfile |
165 | | - |
166 | | -``` |
167 | | -docker build -t safeplaces-backend-expressjs . |
168 | | -``` |
169 | | - |
170 | | -#### Run Dockerfile |
171 | | - |
172 | | -``` |
173 | | -docker run --rm --name safeplaces-expressjs --env-file=.env -p 3000:3000 safeplaces-backend-expressjs |
174 | | -``` |
175 | | - |
176 | | -*Note*: sample env file can be found at .env.template`. |
177 | | - |
178 | | -#### Deploy via docker-compose |
179 | | - |
180 | | - *Using docker-compose will bring a postgres server along with the application container* |
181 | | - |
182 | | -Ensure to create application Environment variables file .env from .env.template |
183 | | - |
184 | | -Ensure to create Postgres Environment variables file .database.env from .database.env.template |
185 | | - |
186 | | -#### Run the following: |
187 | | - |
188 | | -``` |
189 | | -docker-compose build |
190 | | -docker-compose up |
191 | | -``` |
192 | | - |
193 | | -### Testing Your Deployment |
194 | | - |
195 | | -Run: |
| 5 | +GPS Points are collected by the SafePlaces mobile application and persisted across the public and private databases in discreet format. In discreet format, each GPS point consists of a latitude, longitude, a time, and implicitly represents a five minute window of time with the beginning of the five minute window relative to the time property. An example of three consecutive data points (consecutively five minutes apart from each other) in discreet format would look like the following: |
196 | 6 |
|
197 | 7 | ``` |
198 | | -curl http://localhost:3000/health |
| 8 | +[ |
| 9 | + { |
| 10 | + "longitude": 14.91328448, |
| 11 | + "latitude": 41.24060321, |
| 12 | + "time": "2020-05-30T18:25:00.511Z" |
| 13 | + }, |
| 14 | + { |
| 15 | + "longitude": 14.91328448, |
| 16 | + "latitude": 41.24060321, |
| 17 | + "time": "2020-05-30T18:30:00.511Z" |
| 18 | + }, |
| 19 | + { |
| 20 | + "longitude": 14.91328448, |
| 21 | + "latitude": 41.24060321, |
| 22 | + "time": "2020-05-30T18:35:00.511Z" |
| 23 | + } |
| 24 | +] |
199 | 25 | ``` |
200 | 26 |
|
201 | | -Should respond with: |
| 27 | +The contact tracing tool in the SafePlaces Frontend represents points as a function of time spent in a single location. This necessitates the translation of GPS point data from discreet format (above) to duration format. The three points in the above discreet format example would become a single GPS point consisting of latitude, longitude, time (start time), and duration, like the following example, when translated to duration format: |
202 | 28 |
|
203 | 29 | ``` |
204 | 30 | { |
205 | | - "message": "All Ok!" |
| 31 | + "discreetPointIDs": [21, 22, 23], |
| 32 | + "longitude": 14.91328448, |
| 33 | + "latitude": 41.24060321, |
| 34 | + "time": "2020-05-30T18:25:00.511Z", |
| 35 | + "duration": 15 |
206 | 36 | } |
207 | 37 | ``` |
208 | 38 |
|
209 | | -## Security Recommendations |
210 | | -We recommend the following for deployed versions of any and all SafePlace APIs: |
| 39 | +Follow the links below for more information on how to setup and configure the SafePlaces. |
211 | 40 |
|
212 | | -- The following headers (and appropriate values) should be returned from the server to client: |
213 | | -- X-Frame-Options |
214 | | -- X-XSS-Protection |
215 | | -- X-Content-Type-Options |
216 | | -- Expect-CT |
217 | | -- Feature-Policy |
218 | | -- Strict-Transport-Security |
219 | | - - A suitable "Referrer-Policy" header is included, such as "no-referrer" or "same-origin" |
220 | | -- The server running SafePlaces should not expose any information about itself that is unneeded (i.e., type of server (nginx) and version (1.17.8)) |
221 | | - - Implement an appropriate security policy |
222 | | - - All SafePlaces APIs should be deployed behind an appropriately configured firewall |
223 | | - - All requests to and from a SafePlaces API should be over HTTPS |
224 | | - - Old versions of SSL and TLS protocols, algorithms, ciphers, and configuration are disabled, such as SSLv2, SSLv3, or TLS 1.0 and TLS 1.1. The latest version of TLS should be the preferred cipher suite. |
225 | | - - The web server should be configured under a low-privilege system user account. |
226 | | - - Any debug model provided by the web or application server is disabled. |
| 41 | +- [SafePlaces Docs Home](https://github.com/Path-Check/safeplaces-docs/tree/master) |
| 42 | +- [Databases](https://github.com/Path-Check/safeplaces-docs/tree/master/safeplaces-backend-services/databases) |
| 43 | +- [Setting Up SafePlaces Translation Service](https://github.com/Path-Check/safeplaces-docs/tree/master/safeplaces-backend-services/setup#setting-up-safeplaces-translation-service) |
| 44 | +- [Environment Variables](https://github.com/Path-Check/safeplaces-docs/blob/master/safeplaces-backend-services/environment-variables/safeplaces-backend-service.md) |
| 45 | +- [Authentication](https://github.com/Path-Check/safeplaces-docs/tree/master/safeplaces-backend-services/authentication) |
| 46 | +- [User Account & Organization Setup](https://github.com/Path-Check/safeplaces-docs/tree/master/safeplaces-backend-services/accounts-configuration) |
| 47 | +- [Publishing Location Data](https://github.com/Path-Check/safeplaces-docs/tree/master/safeplaces-backend-services/published-data) |
| 48 | +- [Security Recommendations](https://github.com/Path-Check/safeplaces-docs/tree/master/safeplaces-backend-services/security) |
0 commit comments