README
Exposure Notification API Service
Local Development: Running the API and Database
The backend API consists of both a Fastify server and a PostgreSQL database. To get these running will require the following steps. You will need Docker installed to run the database, and you may use Docker to run the API service as well.
You have two options if you want to run the API and database locally: run everything inside Docker or run just the database inside Docker. It's up to you whether you like doing it one way or the other. If the API doesn't appear to be starting correctly outside of a Docker then try running everything inside Docker - the issue might just be a local environment thing.
In either case, basic setup is necessary before anything else. Please run these commands to install dependencies and create a basic environment configuration.
$> npm install
$> npm run create:env
Running API Outside Docker
You can run the API outside of Docker but the database still requires Docker.
First we'll start and setup the database.
$> npm run db:up
# Postgres database is started
$> npm run db:migrate
# Migration script is run to setup the tables and indexes
Next, we'll want to start the API service itself
$> npm run start:dev
[nodemon] 2.0.4
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node .`
[1596743208358] INFO (80 on e1655c760ecf): Server listening at http://0.0.0.0:5000
[1596743208359] INFO (80 on e1655c760ecf): Server running at: http://0.0.0.0:5000
At this point the API service is up and listening on port 5000. Editing files will cause nodemon to restart the service.
Running API with Docker
You can also run the API with Docker as well. This is recommended if running outside of Docker fails for unexpected local environment or dependency conflicts. For example, we've seen issues running the API with Node 14.x as it's only been certified with Node 12.x.
You can start everything with one single command.
$> npm run system:up
....
Starting covid-green-db ... done
Starting covid-green-db-migrations ... done
Starting covid-green-api ... done
Attaching to covid-green-db, covid-green-db-migrations, covid-green-api
....
covid-green-db | 2020-08-06 20:03:49.104 UTC [1] LOG: database system is ready to accept connections
....
covid-green-db-migrations | > while ! node lib/migrate.js; do sleep 1; done && npm run db:check:readiness
covid-green-db-migrations | No migrations run for schema "public". Already at the latest one.
covid-green-db-migrations | Migration done
covid-green-db-migrations |
covid-green-db-migrations | > exposure-notification-api@1.0.0 db:check:readiness /covid-green
covid-green-db-migrations | > node lib/is-database-ready.js
covid-green-db-migrations |
covid-green-db-migrations | Database is Ready: Version 2
covid-green-db-migrations exited with code 0
....
covid-green-api | > npm run db:wait:readiness && npm run start:dev
....
covid-green-api | Database is Ready: Version 2
....
covid-green-api | [nodemon] 2.0.4
covid-green-api | [nodemon] to restart at any time, enter `rs`
covid-green-api | [nodemon] watching path(s): *.*
covid-green-api | [nodemon] watching extensions: js,mjs,json
covid-green-api | [nodemon] starting `node .`
covid-green-api | [1596744238998] INFO (72 on e1655c760ecf): Server listening at http://0.0.0.0:5000
covid-green-api | [1596744238999] INFO (72 on e1655c760ecf): Server running at: http://0.0.0.0:5000
And again, at this point the API service is up and listening on port 5000. You can confirm this with docker ps
$> docker ps
IMAGE PORTS NAMES
covid-green-backend-api_covid-green-api 0.0.0.0:5000->5000/tcp covid-green-api
postgres:10.4-alpine 0.0.0.0:5432->5432/tcp covid-green-db
Editing files outside the container will cause nodemon to restart the service.
Backend API Development
There are a number of handy commands you can run to help with development.
| Command | Action |
|---|---|
npm run start:dev | Run the server in dev mode, automatically restarts on file change |
npm run create:env | Create a new .env file |
npm test | Run unit tests |
npm run test:watch | Run backend tests in watch mode, running on changed test files |
npm run db:migrate | Run database migrations. |
npm run db:up | Run the database server |
npm run db:down | Shutdown the database server |
npm run db:delete | Delete the database server. You will need to run db:up and db:migrate again. |
npm run lint | Run eslint |
npm run lint:fix | Run eslint in fix mode |
api:start:when-ready | Start the API only after the database is ready and migrated |
db:migrate:until-done | Keep trying to migrate the database until it completes successfully |
db:check:readiness | Return 0 rcode if the database is migrated and ready |
db:wait:readiness | Wait until the database is migrated and ready |
system:up | Start everything using docker-compose |
system:down | Stop everything using docker-compose |
system:nuke | Stop and delete everything using docker-compose |
Configuration & Secrets
All the endpoints in this service use varied sets of configuration settings and secrets.
Non Secret Settings
| .env | AWS Property Key | Description |
|---|---|---|
AWS_REGION | None | AWS region where we're running |
CONFIG_VAR_PREFIX | None | Prefix of all configuration property and secret names |
NODE_ENV | None | Some string with env name in it - Some string with 'production' in it means running in production |
API_HOST | api_host | Name of host API is running on |
API_PORT | api_port | Port API is listening on |
ENABLE_CALLBACK | enable_callback | Boolean indicating whether feature is turned on |
ENABLE_CHECK_IN | enable_check_in | Boolean indicating whether feature is turned on |
ENABLE_METRICS | enable_metrics | Boolean indicating whether feature is turned on |
ENABLE_NOTICES | enable_self_isolation_notices | Boolean indicating whether feature is turned on |
LOG_LEVEL | log_level | Standard logging level setting |
CORS_ORIGIN | cors_origin | Boolean indicating something about CORS |
DB_HOST | db_host | Connection host for database (writing/reading) |
DB_READ_HOST | db_read_host | Connection host for database (reading) |
DB_PORT | db_port | Port the database is listening on |
DB_DATABASE | db_database | Name of database to connect to |
DB_SSL | db_ssl | Boolean indicating whether database connection should be SSL |
DEFAULT_REGION | default_region | Default Covid region |
REFRESH_TOKEN_EXPIRY | security_refresh_token_expiry | ?? |
EXPOSURE_LIMIT | ?? | ?? |
CODE_LIFETIME_MINS | security_code_lifetime_mins | ?? |
TOKEN_LIFETIME_MINS | security_token_lifetime_mins | ?? |
UPLOAD_TOKEN_LIFETIME_MINS | upload_token_lifetime_mins | ?? |
VERIFY_RATE_LIMIT_SECS | security_verify_rate_limit_secs | ?? |
CALLBACK_QUEUE_URL | callback_url | ?? |
NOTICES_QUEUE_URL | self_isolation_notices_url | ?? |
ASSETS_BUCKET | s3_assets_bucket | ?? |
CALLBACK_RATE_LIMIT_SECS | security_callback_rate_limit_secs | # of seconds required before a user can request another callback |
CALLBACK_RATE_LIMIT_REQUEST_COUNT | security_callback_rate_limit_request_count | # of callback requests allowed before rate limit goes into effect |
NOTICES_RATE_LIMIT_SECS | security_notices_rate_limit_secs | # of seconds required before a user can request another notice unique key |
Secret Settings
| .env | AWS Secret Key | Field | Meaning |
|---|---|---|---|
DB_USER | rds-read-write-create | username | Database username |
DB_PASSWORD | rds-read-write-create | password | Database password |
ENCRYPT_KEY | encrypt | key | Key used to encrypt things |
JWT_SECRET | jwt | key | ?? |
DEVICE_CHECK_KEY_ID | device-check | keyId | ?? |
DEVICE_CHECK_KEY | device-check | key | ?? |
DEVICE_CHECK_TEAM_ID | device-check | teamId | ?? |
DEVICE_CHECK_PACKAGE_NAME | device-check | apkPackageName | ?? |
DEVICE_CHECK_PACKAGE_DIGEST | device-check | apkDigestSha256 | ?? |
DEVICE_CHECK_CERTIFICATE_DIGEST | device-check | apkCertificateDigestSha256 | ?? |
DEVICE_CHECK_ROOT_CA | device-check | safetyNetRootCa | ?? |
DEVICE_CHECK_TIME_DIFF_THRESHOLD_MINS | device-check | timeDifferenceThresholdMins | ?? |
Team
Lead Maintainers
- @colmharte - Colm Harte colm.harte@nearform.com
- @jasnell - James M Snell jasnell@gmail.com
- @aspiringarc - Gar Mac Críosta gar.maccriosta@hse.ie
Core Team
- @ShaunBaker - Shaun Baker shaun.baker@nearform.com
- @floridemai - Paul Negrutiu paul.negrutiu@nearform.com
- @jackdclark - Jack Clark jack.clark@nearform.com
- @andreaforni - Andrea Forni andrea.forni@nearform.com
- @jackmurdoch - Jack Murdoch jack.murdoch@nearform.com
Contributors
- @fiacc - Fiacc O'Brien Moran fiacc.obrienmoran@nearform.com
Past Contributors
- @dennisgove - Dennis Gove dgove1@bloomberg.net
- @dharding - David J Harding davidjasonharding@gmail.com
Hosted By
Linux Foundation Public Health
Acknowledgements
License
Copyright (c) 2020 HSEIreland Copyright (c) The COVID Green Contributors
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Contributors
Similar repos
Languages
JavaScript
100.0%
README
Exposure Notification API Service
Local Development: Running the API and Database
The backend API consists of both a Fastify server and a PostgreSQL database. To get these running will require the following steps. You will need Docker installed to run the database, and you may use Docker to run the API service as well.
You have two options if you want to run the API and database locally: run everything inside Docker or run just the database inside Docker. It's up to you whether you like doing it one way or the other. If the API doesn't appear to be starting correctly outside of a Docker then try running everything inside Docker - the issue might just be a local environment thing.
In either case, basic setup is necessary before anything else. Please run these commands to install dependencies and create a basic environment configuration.
$> npm install
$> npm run create:env
Running API Outside Docker
You can run the API outside of Docker but the database still requires Docker.
First we'll start and setup the database.
$> npm run db:up
# Postgres database is started
$> npm run db:migrate
# Migration script is run to setup the tables and indexes
Next, we'll want to start the API service itself
$> npm run start:dev
[nodemon] 2.0.4
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node .`
[1596743208358] INFO (80 on e1655c760ecf): Server listening at http://0.0.0.0:5000
[1596743208359] INFO (80 on e1655c760ecf): Server running at: http://0.0.0.0:5000
At this point the API service is up and listening on port 5000. Editing files will cause nodemon to restart the service.
Running API with Docker
You can also run the API with Docker as well. This is recommended if running outside of Docker fails for unexpected local environment or dependency conflicts. For example, we've seen issues running the API with Node 14.x as it's only been certified with Node 12.x.
You can start everything with one single command.
$> npm run system:up
....
Starting covid-green-db ... done
Starting covid-green-db-migrations ... done
Starting covid-green-api ... done
Attaching to covid-green-db, covid-green-db-migrations, covid-green-api
....
covid-green-db | 2020-08-06 20:03:49.104 UTC [1] LOG: database system is ready to accept connections
....
covid-green-db-migrations | > while ! node lib/migrate.js; do sleep 1; done && npm run db:check:readiness
covid-green-db-migrations | No migrations run for schema "public". Already at the latest one.
covid-green-db-migrations | Migration done
covid-green-db-migrations |
covid-green-db-migrations | > exposure-notification-api@1.0.0 db:check:readiness /covid-green
covid-green-db-migrations | > node lib/is-database-ready.js
covid-green-db-migrations |
covid-green-db-migrations | Database is Ready: Version 2
covid-green-db-migrations exited with code 0
....
covid-green-api | > npm run db:wait:readiness && npm run start:dev
....
covid-green-api | Database is Ready: Version 2
....
covid-green-api | [nodemon] 2.0.4
covid-green-api | [nodemon] to restart at any time, enter `rs`
covid-green-api | [nodemon] watching path(s): *.*
covid-green-api | [nodemon] watching extensions: js,mjs,json
covid-green-api | [nodemon] starting `node .`
covid-green-api | [1596744238998] INFO (72 on e1655c760ecf): Server listening at http://0.0.0.0:5000
covid-green-api | [1596744238999] INFO (72 on e1655c760ecf): Server running at: http://0.0.0.0:5000
And again, at this point the API service is up and listening on port 5000. You can confirm this with docker ps
$> docker ps
IMAGE PORTS NAMES
covid-green-backend-api_covid-green-api 0.0.0.0:5000->5000/tcp covid-green-api
postgres:10.4-alpine 0.0.0.0:5432->5432/tcp covid-green-db
Editing files outside the container will cause nodemon to restart the service.
Backend API Development
There are a number of handy commands you can run to help with development.
| Command | Action |
|---|---|
npm run start:dev | Run the server in dev mode, automatically restarts on file change |
npm run create:env | Create a new .env file |
npm test | Run unit tests |
npm run test:watch | Run backend tests in watch mode, running on changed test files |
npm run db:migrate | Run database migrations. |
npm run db:up | Run the database server |
npm run db:down | Shutdown the database server |
npm run db:delete | Delete the database server. You will need to run db:up and db:migrate again. |
npm run lint | Run eslint |
npm run lint:fix | Run eslint in fix mode |
api:start:when-ready | Start the API only after the database is ready and migrated |
db:migrate:until-done | Keep trying to migrate the database until it completes successfully |
db:check:readiness | Return 0 rcode if the database is migrated and ready |
db:wait:readiness | Wait until the database is migrated and ready |
system:up | Start everything using docker-compose |
system:down | Stop everything using docker-compose |
system:nuke | Stop and delete everything using docker-compose |
Configuration & Secrets
All the endpoints in this service use varied sets of configuration settings and secrets.
Non Secret Settings
| .env | AWS Property Key | Description |
|---|---|---|
AWS_REGION | None | AWS region where we're running |
CONFIG_VAR_PREFIX | None | Prefix of all configuration property and secret names |
NODE_ENV | None | Some string with env name in it - Some string with 'production' in it means running in production |
API_HOST | api_host | Name of host API is running on |
API_PORT | api_port | Port API is listening on |
ENABLE_CALLBACK | enable_callback | Boolean indicating whether feature is turned on |
ENABLE_CHECK_IN | enable_check_in | Boolean indicating whether feature is turned on |
ENABLE_METRICS | enable_metrics | Boolean indicating whether feature is turned on |
ENABLE_NOTICES | enable_self_isolation_notices | Boolean indicating whether feature is turned on |
LOG_LEVEL | log_level | Standard logging level setting |
CORS_ORIGIN | cors_origin | Boolean indicating something about CORS |
DB_HOST | db_host | Connection host for database (writing/reading) |
DB_READ_HOST | db_read_host | Connection host for database (reading) |
DB_PORT | db_port | Port the database is listening on |
DB_DATABASE | db_database | Name of database to connect to |
DB_SSL | db_ssl | Boolean indicating whether database connection should be SSL |
DEFAULT_REGION | default_region | Default Covid region |
REFRESH_TOKEN_EXPIRY | security_refresh_token_expiry | ?? |
EXPOSURE_LIMIT | ?? | ?? |
CODE_LIFETIME_MINS | security_code_lifetime_mins | ?? |
TOKEN_LIFETIME_MINS | security_token_lifetime_mins | ?? |
UPLOAD_TOKEN_LIFETIME_MINS | upload_token_lifetime_mins | ?? |
VERIFY_RATE_LIMIT_SECS | security_verify_rate_limit_secs | ?? |
CALLBACK_QUEUE_URL | callback_url | ?? |
NOTICES_QUEUE_URL | self_isolation_notices_url | ?? |
ASSETS_BUCKET | s3_assets_bucket | ?? |
CALLBACK_RATE_LIMIT_SECS | security_callback_rate_limit_secs | # of seconds required before a user can request another callback |
CALLBACK_RATE_LIMIT_REQUEST_COUNT | security_callback_rate_limit_request_count | # of callback requests allowed before rate limit goes into effect |
NOTICES_RATE_LIMIT_SECS | security_notices_rate_limit_secs | # of seconds required before a user can request another notice unique key |
Secret Settings
| .env | AWS Secret Key | Field | Meaning |
|---|---|---|---|
DB_USER | rds-read-write-create | username | Database username |
DB_PASSWORD | rds-read-write-create | password | Database password |
ENCRYPT_KEY | encrypt | key | Key used to encrypt things |
JWT_SECRET | jwt | key | ?? |
DEVICE_CHECK_KEY_ID | device-check | keyId | ?? |
DEVICE_CHECK_KEY | device-check | key | ?? |
DEVICE_CHECK_TEAM_ID | device-check | teamId | ?? |
DEVICE_CHECK_PACKAGE_NAME | device-check | apkPackageName | ?? |
DEVICE_CHECK_PACKAGE_DIGEST | device-check | apkDigestSha256 | ?? |
DEVICE_CHECK_CERTIFICATE_DIGEST | device-check | apkCertificateDigestSha256 | ?? |
DEVICE_CHECK_ROOT_CA | device-check | safetyNetRootCa | ?? |
DEVICE_CHECK_TIME_DIFF_THRESHOLD_MINS | device-check | timeDifferenceThresholdMins | ?? |
Team
Lead Maintainers
- @colmharte - Colm Harte colm.harte@nearform.com
- @jasnell - James M Snell jasnell@gmail.com
- @aspiringarc - Gar Mac Críosta gar.maccriosta@hse.ie
Core Team
- @ShaunBaker - Shaun Baker shaun.baker@nearform.com
- @floridemai - Paul Negrutiu paul.negrutiu@nearform.com
- @jackdclark - Jack Clark jack.clark@nearform.com
- @andreaforni - Andrea Forni andrea.forni@nearform.com
- @jackmurdoch - Jack Murdoch jack.murdoch@nearform.com
Contributors
- @fiacc - Fiacc O'Brien Moran fiacc.obrienmoran@nearform.com
Past Contributors
- @dennisgove - Dennis Gove dgove1@bloomberg.net
- @dharding - David J Harding davidjasonharding@gmail.com
Hosted By
Linux Foundation Public Health
Acknowledgements
License
Copyright (c) 2020 HSEIreland Copyright (c) The COVID Green Contributors
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Similar repos
Contributors
Languages
JavaScript
100.0%