Skip to content

Commit 4a36b7e

Browse files
danilo-delbussodanilo-delbusso
committed
Update README.md
1 parent 26204ad commit 4a36b7e

File tree

2 files changed

+240
-28
lines changed

2 files changed

+240
-28
lines changed

‎README.md

Lines changed: 240 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,270 @@
1-
# Contents
1+
# User Guide
22

3-
- [Installing and Running](#installing-and-running)
4-
* [Installing Server and Web Application](#installing-server-and-web-application)
5-
+ [Non-Docker Installation](#non-docker-installation)
6-
* [Installing the Android Application](#installing-the-android-application)
7-
+ [Non-apk Installation](#non-apk-installation)
8-
* [Notes](#notes)
3+
If possible, please read the `README.pdf` file instead. It contains images and better formatting.
94

10-
# Installing and Running
5+
## System Requirements
116

12-
This document will walk you through installing and running the various software modules for this work.
7+
### Server and Web Application
138

14-
It assumes that you have a working version of Docker and Docker Compose running on your machine. To learn more, please visit [Docker's Installation Guide](https://docs.docker.com/engine/install/) and [Docker Compose's Installation Guide](https://docs.docker.com/compose/install/)
9+
The software was developed using the **Ubuntu 20.04.2.0 LTS (Focal Fossa)** distribution of
10+
the GNU/Linux operating system. It is advised to run the Server and Web Application modules
11+
on **GNU/Linux distributions based on Debian**. Still, the use of the Docker installation
12+
allows them to be run on other operating systems. The reader should however be aware that
13+
they have not been tested and no claims of compatibility have been made.
14+
The Web Application has been developed and tested for **Google Chrome 89.0**. It is
15+
suggested the reader uses this browser.
1516

16-
Moreover, it assumes you are running on a linux distribution. While this is not a requirement, it is advised.
17+
### Mobile Application
1718

18-
# Installing Server and Web Application
19+
The Mobile Application runs solely on Android devices. Furthermore, such devices need to have
20+
the following characteristics:
1921

20-
The Server module will contain a REST API, available at `http://localhost:4683` by default. If you want to change this port, you need to edit its references in the `Dockerfile` and `docker-compose.yml`. You can find these files under the `server` folder. Similarly, the Web Application (named *client*), will be available at `http://localhost:3000`.
22+
- **Android Version 10** or above (other versions might work but have not been tested)
23+
- Working **WiFi and Location functions** accessible through the built-in APIs
24+
- Access to battery optimisation settings to **disable Doze and App Standby**
2125

22-
Before starting, make sure no processes are running on at ports `3000`, `4683`, and `27017`.
26+
## Installing and Running
2327

24-
If you have installed `npm` on your machine, you can kill all processes running on these ports by using the following:
28+
This document will walk you through installing and running the various software modules for
29+
this work.
30+
It assumes that you have a working version of **Docker** and **Docker Compose** running
31+
on your machine. To learn more, please consult Docker’s Installation Guide^1 and Docker
32+
Compose’s Installation Guide^2.
33+
Moreover, it assumes you are running on a **GNU/Linux distribution based on Debian**.
34+
While this is not a strict requirement, it is advised.
35+
36+
(^1) Available at [https://docs.docker.com/engine/install](https://docs.docker.com/engine/install) as of the 1st of April, 2021
37+
38+
39+
(^2) Available at [https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/) as of 1 stof April, 2021
40+
41+
### Installing Server and Web Application
42+
43+
The Server module will contain a REST API, available athttp://localhost:4683by de-
44+
fault. If you want to change this port, you need to edit its reference in theDockerfile
45+
anddocker-compose.yml, as well as updating the.envfile. You can find these files un-
46+
der the _server_ folder. Similarly, the Web Application (named _client_ ), will be available at
47+
[http://localhost:3000.](http://localhost:3000.)
48+
49+
Before starting, make sure no processes are running on at ports `3000` , `4683` , and `27017`. This
50+
includes stopping any existing mongod services that might be running on port 27017.
51+
If you have installed `npm` on your machine, you can kill all processes running on these ports
52+
by using the following:
2553
```zsh
2654
npx kill-port 3000 4683 27017
2755
```
2856

29-
The installation is fairly straightforward. Assuming you have installed Docker an Docker Compose, run the following command from the root folder of the project.
57+
#### Docker Installation
58+
59+
The installation is fairly straightforward. Assuming you have installed Docker an Docker
60+
Compose, run the following command from the root folder of the project.
3061

3162
```zsh
32-
docker-compose up
33-
```
63+
docker -compose up
64+
```
65+
66+
The Server runs on the PM2^4 process manager. By default it will use **all** the cores available
67+
to it. To change this option, modify the `instances` property in the `ecosystem.config.js` file to the number of cores you want (e.g. `instances : 1`).
68+
69+
The process might take a while. Please wait for the client to be running.
70+
71+
#### Non-Docker Installation
72+
If you cannot install Docker or Docker Compose, or prefer not to, installation guides are available
73+
in the project files at `server/README.md` and `client/README.md`.
74+
75+
### Installing the Android Application
76+
77+
The Android Application can be installed using the `app.apk` package found under the _android-app_
78+
folder, which can be manually installed on an Android Device. An article from **thecustomdroid**^5 walks through the process in detail.
79+
80+
(^3) On Ubuntu 20.04, you can use `sudo systemctl stop mongod`
81+
82+
(^4) Package available at [https://www.npmjs.com/package/pm2](https://www.npmjs.com/package/pm2) as of 1st of April 2021
83+
84+
(^5) Available at [https://www.thecustomdroid.com/how-to-install-apk-on-android](https://www.thecustomdroid.com/how-to-install-apk-on-android) as of 1st of April 2021
85+
86+
87+
**Non-apk Installation**
88+
In order to install the Android Application without the use of an apk file, you’ll need to install
89+
Android Studio^6 and follow the steps described in the official documentation^7.
90+
91+
### Caching Function
92+
93+
The caching function is a simple script that is meant to run using the Lambda service offered
94+
by Amazon Web Services. As such, it is not meant to be run. However, if you want to use it to
95+
start the caching operation of map data, then do the following:
96+
97+
1. Make sure the REST API is running on port **4683**.
98+
2. Install dependencies:
99+
`npm install`
100+
3. Then edit `index.js` and add the following line at the end of the file :
101+
`startRequest()`
102+
4. Finally, run the script by using
103+
`node index`
104+
This will send two `PATCH` requests to the REST API, which will start the caching process.
105+
106+
## Initial Configuration
107+
108+
While the Dockerised install contains a configuration that will work for a demo, it can be
109+
modified. Moreover, the Mobile Application needs to be configured to work properly on startup.
110+
This section will walk through the process of doing so.
111+
112+
### Server
113+
114+
The Docker installation contains a pre-packaged configuration in the form of an .env file. While
115+
it is useful to demo and run the application, it is important to change the values for security
116+
reasons for extensive use. An overview of the used .env values is available at Table E.1.
117+
118+
(^6) Available at [https://developer.android.com/studio/install](https://developer.android.com/studio/install) as of 1st of April 2021
119+
120+
(^7) Available at [https://developer.android.com/studio/run](https://developer.android.com/studio/run) as of 1st of April 2021
121+
122+
123+
| Name | Description |
124+
|------------------------ |---------------------------------------------------------- |
125+
| PORT | The server’s port |
126+
| DOMAIN | The server’s domain |
127+
| API_PREFIX | The base URL for the API |
128+
| DOCKER_ENV | true if the Server has to run in a Docker container |
129+
| DOCKER_DATABASE_URL | The MongoDB URL used when DOCKER_ENV is "true" |
130+
| DATABASE_URL | The MongoDB URL used when not DOCKER_ENV isn’t "true" |
131+
| DB_NAME | The name of the database |
132+
| TOKEN_KEY | The key used to generate JWTs |
133+
| TOKEN_EXPIRATION_TIME | The time of expiry for JWTs |
134+
| DEV_UPLOAD_TOKEN | A special token that bypasses token validation |
135+
| CACHE_ON_STARTUP | Load cached features and heat-map data when first start- |
136+
| GEOJSON_URL | URL of the GEOJson feature collection used to cache data |
137+
138+
*Table E.1: The .env configuration variables available for the server module*
139+
140+
### Web Application
141+
142+
The Docker installation contains a pre-packaged configuration in the form of an .env file. While
143+
it is useful to demo and run the application, it is important to change the values for security
144+
reasons for extensive use. An overview of the used .env values is available at Table E.2.
145+
146+
| Name | Description |
147+
|--------------------------------- |--------------------------------------------------------------- |
148+
| REACT_APP_MODE | production if running the app in production, dev if otherwise |
149+
| REACT_APP_SERVER_URL_PRODUCTION | The URL of the API when REACT_APP_MODE=production |
150+
| REACT_APP_SERVER_URL | The URL of the API when REACT_APP_MODE=dev |
151+
152+
*Table E.2: The .env configuration variables available for the client module*
153+
154+
### Mobile Application
155+
156+
#### Enabling Permissions
157+
158+
159+
Upon starting the application, you will be
160+
shown several information screens. After read-
161+
ing through all of them you will be prompted
162+
to enable location permissions for the application. Please choose to Allow all the time.
163+
If you choose to only enable it While using
164+
the app , background collection of data will
165+
not work as designed.
166+
The device will also need to have Location and WiFi services enabled in order
167+
to work scan for WiFi signals.
168+
169+
170+
#### Setting Preferences
171+
172+
The version of the application available for install contains special Developer menus. They
173+
can be found by clicking on the gear icon on
174+
the main page.
175+
Here, preferences can be set. You should
176+
**update the URL value** with the URL and
177+
port of the Server application. It is found under **Settings > Preferences > API Settings > URL**. Once set up, operations of scan uploads and risk analysis will work
178+
as designed.
179+
Similarly, under the **Settings > Preferences > Risk Analysis** menu you will be able to
180+
**modify the constants used to perform Risk Analysis**.
181+
It is suggested that you also **enable location logging** under **Settings > Preferences > Location Logging > Enable Location Logging**. This will allow you to upload location data to the Exposure Ingestion Service and see it visualised in the Web Application.
182+
183+
184+
## Functionality & User Interface
185+
186+
This section will list the core functionalities available through the User Interfaces developed for
187+
each module.
188+
189+
### Server
190+
191+
The Server does not contain any User Interface, as its main role is that of an API. However,
192+
Users that wish can access an interactive documentation HTML page generate through the
193+
Swagger library^8.
194+
In order to access it, simply open a web browser athttp://<DOMAIN>:<PORT>/api-docs^9.
195+
You will be able to test the supported endpoints by clicking on the **Try it out** button. Make
196+
sure that the Server is running and the database is connected.
197+
198+
(^89) More information available at https://swagger.io/
199+
For the default dockerised configuration, go to http://localhost:4683/api-docs/
200+
201+
202+
### Web Application
203+
204+
205+
By default, the Web Application will be available at http://localhost:3000. All pages can
206+
be reached by using the navigation menu on the left side of the layout.
207+
208+
#### Map
209+
210+
This page contains an interactive map. After the loading is complete, it’s possible to move
211+
around the map by holding and dragging the mouse cursor.
212+
213+
#### Layout Options
214+
On the top-right corner of the map it’s possible to modify the following setting:
215+
216+
217+
- Choose the theme of the map. Light or Dark.
218+
- Toggle the Heat-map on.
219+
- Toggle the subdivision polygons that show contagion summaries.
220+
If you want to visualise data about the new scans you’ve uploaded, make sure you’ve refreshed
221+
the cached data by either using the caching function, or by sending a PATCH request to the
222+
caching endpoints.
223+
224+
225+
#### Division Details
226+
227+
You can hover over subdivisions to see a Popup showing details about the cached contagion
228+
data for that specific area. If the subdivisions are not visible, check the _Show Data_ tick-box in
229+
the layer options.
230+
231+
### Mobile Application
34232

35-
The process might take a while. Please wait for the client to be run.
233+
#### Main Activity
36234

37-
## Non-Docker Installation
235+
The Main Activity shows the current status of scanning. Opening the Main Activity will create
236+
a sticky notification that shows the current status of the scanning.
237+
If the location or WiFi services are turned off, a different notification will be shown, prompting
238+
you to turn them on.
239+
You can enter the **Settings Activity** by tapping on the cog icon on the top-right corner of
240+
the page.
38241

39-
If you cannot install Docker or Docker Compose, or prefer not to, installation guides are available at `server/README.md` and `client/README.md`. These installations will require `Node.js`, `npm`, and `MongoDB`.
242+
**Settings Activity**
40243

244+
By tapping on the **Preferences** button, you can update the preferences of the application,
245+
including enabling location logging and modifying API and Risk Analysis settings.
41246

42-
# Installing the Android Application
247+
**Upload Scans**
43248

44-
The Android Application can be installed using the `app.apk` package, which can be manually installed on an Android Device. [This article from thecustomdroid](https://www.thecustomdroid.com/how-to-install-apk-on-android/) walks through the process in detail.
249+
Upload Scans allows you to test the upload of Access Points data to the Exposure Ingestion
250+
Service. You can choose to also send location data by checking the Switch component on screen.
251+
To upload the currently stored scans and WiFi locations, simply press **Upload Scans**.
252+
It also shows two metrics: _Scans_ , the number of scans performed, and _AP Scans_ , the number
253+
of individual scans of each Access Point.
45254

255+
**Manage Data**.
46256

257+
From this screen, you can manage Access Point data stored remotely on the Server’s database,
258+
as well as the scan data stored on the device. Tapping **Delete Collection** will delete the _scans_
259+
collection in the back-end. Tapping **Delete Data** will delete the locally stored data.
47260

48-
## Non-apk Installation
261+
**Check Exposure**
49262

50-
In order to install the Android Application without the use of an `apk` file, you'll need to install [Android Studio](https://developer.android.com/studio/install) and follow the steps described in the [official documentation](https://developer.android.com/studio/run).
263+
This page will allow you to test the Risk Analysis performed by the application. Clicking
264+
on **Check Exposure** will simulate the period exposure check performed by the application
265+
every 12 hours. To change the constants used for the Risk Analysis, please go to **Preferences > Developer Options**.
51266

52267

53268

54-
# Notes
55269

56-
The Mobile Application needs to connect to the Server. In order to do so, it needs to have direct access to it through the network This can be achieved by connecting the Android Device to the same network where the Server is running on. Assuming there is no restriction, the app will connect to the API.
57270

58-
You can change the IP and port of the Server by clicking on the spanner symbol on the top right corner of the application. This button will open the settings of the application, from which you can change the API URL by typing it and clicking "Save"

‎README.pdf

817 KB
Binary file not shown.

0 commit comments

Comments
 (0)