parent
e1fea72905
commit
6f7f6d0bfa
@ -0,0 +1,7 @@ |
||||
# Air Quality Web |
||||
|
||||
> The Web Interface for the _Monitair_ project. |
||||
|
||||
This is the documentation for [Air Quality Web](https://github.com/ConnectedHumber/Air-Quality-Web/), the air quality web interface that displays data from sensors scattered about the globe. |
||||
|
||||
Check out the sections in the sidebar for documentation on the installation process, configuring an installation, and the HTTP API provided. |
@ -0,0 +1,102 @@ |
||||
# Getting Started |
||||
To get started, there are 3 main steps: |
||||
|
||||
1. Cloning & building the application |
||||
2. Configuring the application |
||||
3. Configuration a web server |
||||
|
||||
The process is outlined in detail below. |
||||
|
||||
|
||||
## System Requirements |
||||
- Git |
||||
- Bash (if on Windows, try [Git Bash](https://gitforwindows.org/)) - the build script is written in Bash |
||||
- PHP 7+ enabled web server |
||||
- _Nginx_ + _PHP-FPM_ is recommended |
||||
- Apache works too |
||||
- MariaDB database with the appropriate table structure pre-loaded |
||||
- Node.JS (preferably 10+) + [npm](https://npmjs.org/) 6+ (for installing & building the client-side app code) |
||||
- [Node.JS](https://nodejs.org/) |
||||
- [Composer](https://getcomposer.org/) (for installing server-side dependencies) |
||||
- PHP modules: |
||||
- `pdo-mysql` (for the database connection) |
||||
- A [MariaDB](https://mariadb.com/) server with a database already setup with the schema data in it. Please get in contact with [ConnectedHumber](https://connectedhumber.org/) for information about the database schema and structure. |
||||
|
||||
|
||||
## Installation |
||||
1. Start by cloning this repository: |
||||
|
||||
```bash |
||||
git clone https://github.com/ConnectedHumber/Air-Quality-Web.git |
||||
``` |
||||
|
||||
|
||||
2. `cd` into the root of the cloned repository. Then install the dependencies (these are installed locally): |
||||
|
||||
```bash |
||||
./build setup setup-dev |
||||
``` |
||||
|
||||
|
||||
3. Build the client-side application: |
||||
|
||||
```bash |
||||
# For development, run this: |
||||
./build client |
||||
# For production, run this: |
||||
NODE_ENV=production ./build client |
||||
# If you're actively working on the codebase and need to auto-recompile on every change, run this: |
||||
./build client-watch |
||||
``` |
||||
|
||||
4. Change the ownership to allow your web server user to access the created directory. Usually, the web server will be running under the `www-data` user: |
||||
|
||||
```bash |
||||
sudo chown -R www-data:www-data path/to/Air-Quality-Web |
||||
``` |
||||
|
||||
|
||||
5. Edit `data/settings.toml` to enter your database credentials. |
||||
|
||||
You can edit other settings here too. See `settings.default.toml` for the settings you can change, but do **not** edit `settings.default.toml`! Edit `data/settings.toml` instead. You'll probably want to give the entire default settings file a careful read. |
||||
|
||||
|
||||
6. Configure your web server to serve the root of the repository you've cloned if you haven't already. Skip this step if you cloned the repository into a directory that your web server already serves. |
||||
|
||||
|
||||
7. Disallow public access to the private `data` directory. |
||||
|
||||
In Nginx: |
||||
|
||||
```nginx |
||||
# Put this inside the "server { }" website definition block: |
||||
# The "server { }" block can usually be found somewhere in /etc/nginx on Linux machines, and may have a "server_name" directive specifying the domain name it's serving if multiple websites are configured. |
||||
location ^~ /path/to/data/directory { |
||||
deny all; |
||||
} |
||||
``` |
||||
|
||||
In Apache: |
||||
|
||||
```htaccess |
||||
# Create a file called ".htaccess" with this content inside the data/ directory |
||||
Require all denied |
||||
``` |
||||
|
||||
|
||||
8. Test the application with an API call. If this returns valid JSON, then you've set it up correctly |
||||
|
||||
``` |
||||
http://example.com/path/to/Air-Quality-Web/api.php?action=list-devices |
||||
``` |
||||
|
||||
|
||||
9. (Optional) Setup HTTPS: |
||||
|
||||
```bash |
||||
sudo apt install certbot |
||||
# On Nginx: |
||||
sudo certbot --nginx --domain example.com |
||||
# On Apache: |
||||
sudo certbot --apache --domain example.com |
||||
``` |
@ -0,0 +1,110 @@ |
||||
# API |
||||
The server-side API is accessed through `api.php`, and supports a number of GET parameters. The most important of these is the `action` parameter, Which determines what the API will do. The following values are supported: |
||||
|
||||
## version |
||||
> Returns the version of the application. |
||||
|
||||
_No parameters are currently supported by this action._ |
||||
|
||||
Examples: |
||||
|
||||
|
||||
``` |
||||
https://example.com/path/to/api.php?action=version |
||||
``` |
||||
|
||||
|
||||
## fetch-data |
||||
> Fetches air quality data from the system for a specific data type at a specific date and time. |
||||
|
||||
Parameter | Type | Meaning |
||||
--------------------|-----------|--------------------- |
||||
`datetime` | date/time | Required. Specifies the date and time for which readings are desired. For current data use the special keyword `now`. |
||||
`reading_type` | string | Required. Specifies the type of reading desired. |
||||
`format` | string | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`. |
||||
|
||||
Examples: |
||||
|
||||
``` |
||||
https://example.com/path/to/api.php?action=fetch-data&datetime=2019-01-03%2007:52:10&reading_type=PM10 |
||||
https://example.com/path/to/api.php?action=fetch-data&datetime=now&reading_type=PM10 |
||||
``` |
||||
|
||||
## list-devices |
||||
> Fetches a list of devices currently in the system. |
||||
|
||||
Parameter | Type | Meaning |
||||
--------------------|-----------|--------------------- |
||||
`only-with-location`| bool | Optional. If present only devices with a defined location will be returned. Useful for getting a list of devices to place on a map. |
||||
`format` | string | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`. |
||||
|
||||
Examples: |
||||
|
||||
``` |
||||
https://example.com/path/to/api.php?action=list-devices |
||||
https://example.com/path/to/api.php?action=list-devices&only-with-location=yes |
||||
``` |
||||
|
||||
## device-info |
||||
> Gets (lots of) information about a single device. |
||||
|
||||
Parameter | Type | Meaning |
||||
--------------------|-----------|--------------------- |
||||
`device-id` | int | Required. The id of the device to get extended information for. See the `list-device` action for how to get a hold of one. |
||||
|
||||
Examples: |
||||
|
||||
## list-reading-types |
||||
> Lists the different types of readings that can be specified. |
||||
|
||||
Parameter | Type | Meaning |
||||
--------------------|-----------|--------------------- |
||||
`device-id` | int | Optional. If specified, this filters the list of measurement types to list only those reported by the device with the specified id. |
||||
`format` | string | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`. |
||||
|
||||
``` |
||||
https://example.com/path/to/api.php?action=list-reading-types |
||||
https://example.com/path/to/api.php?action=list-reading-types&device-id=22 |
||||
https://example.com/path/to/api.php?action=list-reading-types&device-id=54 |
||||
``` |
||||
|
||||
|
||||
## device-data-bounds |
||||
> Gets the start and end DateTime bounds for the data recorded for a specific device. |
||||
|
||||
Parameter | Type | Meaning |
||||
--------------------|-----------|--------------------- |
||||
`device-id` | int | Required. The id of the device to get the data DateTime bounds for. |
||||
|
||||
``` |
||||
https://example.com/path/to/api.php?action=device-data-bounds&device-id=18 |
||||
https://example.com/path/to/api.php?action=device-data-bounds&device-id=11 |
||||
``` |
||||
|
||||
## device-data |
||||
> Gets data by device given a start and end time. |
||||
|
||||
Parameter | Type | Meaning |
||||
--------------------|-----------|--------------------- |
||||
`device-id` | int | The id of the device to get data for. |
||||
`reading-type` | string | The type of reading to obtain data for. |
||||
`start` | datetime | The starting datetime. |
||||
`end` | datetime | The ending datetime. |
||||
`average-seconds` | int | Optional. If specified, readings will be grouped into lumps of this many seconds and averaged. For example a value of 3600 (1 hour) will return 1 data point per hour, with the value of each point an average of all the readings for that hour. |
||||
`format` | string | Optional. Specifies the format that the response will be returned in. Valid values: `json`, `csv`. Default: `json`. |
||||
|
||||
``` |
||||
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=2019-01-20T18:14:59.992Z |
||||
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=2019-01-20T18:14:59.992Z&average-seconds=3600 |
||||
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=now&average-seconds=3600&format=csv |
||||
``` |
||||
|
||||
|
||||
## changelog |
||||
> Gets the changelog as a fragment of HTML. |
||||
|
||||
_No parameters are currently supported by this action._ |
||||
|
||||
``` |
||||
https://example.com/path/to/api.php?action=changelog |
||||
``` |
@ -0,0 +1,7 @@ |
||||
# Documentation |
||||
|
||||
* [Welcome!](./00-Welcome.md) |
||||
* [Production Instance](https://aq.connectedhumber.org/app/) |
||||
* [Getting Started](01-Getting-Started.md) |
||||
* [Changelog](https://github.com/ConnectedHumber/Air-Quality-Web/blob/master/Changelog.md#changelog) |
||||
* [API Docs](05-API-Docs.md) |
File diff suppressed because it is too large
Load Diff
@ -1,45 +1,55 @@ |
||||
{ |
||||
"name": "air-quality-mapper", |
||||
"version": "0.1.0", |
||||
"description": "The web interface and JSON api for the ConnectedHumber Air Quality Monitoring Project.", |
||||
"main": "index.mjs", |
||||
"scripts": { |
||||
"test": "echo \"Error: no test specified\" && exit 1" |
||||
}, |
||||
"repository": { |
||||
"type": "git", |
||||
"url": "git+https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface.git" |
||||
}, |
||||
"author": "Starbeamrainbowlabs", |
||||
"license": "MPL-2.0", |
||||
"bugs": { |
||||
"url": "https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface/issues" |
||||
}, |
||||
"homepage": "https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface#readme", |
||||
"dependencies": { |
||||
"chart.js": "^2.7.3", |
||||
"dom-create-element-query-selector": "github:hekigan/dom-create-element-query-selector", |
||||
"leaflet": "^1.4.0", |
||||
"leaflet-fullscreen": "^1.0.2", |
||||
"leaflet-timedimension": "^1.1.0", |
||||
"leaflet.markercluster": "^1.4.1", |
||||
"moment": "^2.24.0", |
||||
"nanomodal": "^5.1.1", |
||||
"smartsettings": "^1.2.3", |
||||
"tabs": "^0.2.0" |
||||
}, |
||||
"devDependencies": { |
||||
"@types/chart.js": "^2.7.48", |
||||
"@types/leaflet": "^1.4.3", |
||||
"@types/leaflet-fullscreen": "^1.0.4", |
||||
"leaflet-heatmap": "^1.0.0", |
||||
"postcss-copy": "^7.1.0", |
||||
"postcss-import": "^12.0.1", |
||||
"rollup": "^1.6.0", |
||||
"rollup-plugin-commonjs": "^9.2.1", |
||||
"rollup-plugin-node-resolve": "^4.0.1", |
||||
"rollup-plugin-postcss": "^2.0.3", |
||||
"rollup-plugin-replace": "^2.1.0", |
||||
"rollup-plugin-terser": "^4.0.4" |
||||
} |
||||
"name": "air-quality-mapper", |
||||
"version": "0.1.0", |
||||
"description": "The web interface and JSON api for the ConnectedHumber Air Quality Monitoring Project.", |
||||
"main": "index.mjs", |
||||
"scripts": { |
||||
"test": "echo \"Error: no test specified\" && exit 1" |
||||
}, |
||||
"repository": { |
||||
"type": "git", |
||||
"url": "git+https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface.git" |
||||
}, |
||||
"author": "Starbeamrainbowlabs", |
||||
"license": "MPL-2.0", |
||||
"bugs": { |
||||
"url": "https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface/issues" |
||||
}, |
||||
"homepage": "https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface#readme", |
||||
"dependencies": { |
||||
"chart.js": "^2.7.3", |
||||
"dom-create-element-query-selector": "github:hekigan/dom-create-element-query-selector", |
||||
"leaflet": "^1.4.0", |
||||
"leaflet-fullscreen": "^1.0.2", |
||||
"leaflet-timedimension": "^1.1.0", |
||||
"leaflet.markercluster": "^1.4.1", |
||||
"moment": "^2.24.0", |
||||
"nanomodal": "^5.1.1", |
||||
"smartsettings": "^1.2.3", |
||||
"tabs": "^0.2.0" |
||||
}, |
||||
"devDependencies": { |
||||
"@types/chart.js": "^2.7.48", |
||||
"@types/leaflet": "^1.4.3", |
||||
"@types/leaflet-fullscreen": "^1.0.4", |
||||
"docpress": "^0.7.6", |
||||
"leaflet-heatmap": "^1.0.0", |
||||
"postcss-copy": "^7.1.0", |
||||
"postcss-import": "^12.0.1", |
||||
"rollup": "^1.6.0", |
||||
"rollup-plugin-commonjs": "^9.2.1", |
||||
"rollup-plugin-node-resolve": "^4.0.1", |
||||
"rollup-plugin-postcss": "^2.0.3", |
||||
"rollup-plugin-replace": "^2.1.0", |
||||
"rollup-plugin-terser": "^4.0.4" |
||||
}, |
||||
"docpress": { |
||||
"github": "ConnectedHumber/Air-Quality-Web", |
||||
"markdown": { |
||||
"xhtmlOut": true |
||||
}, |
||||
"css": [ |
||||
"docs/theme.css" |
||||
] |
||||
} |
||||
} |
||||
|
Loading…
Reference in new issue