/covid-green-backend-api

Primary LanguageJavaScriptApache License 2.0Apache-2.0

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

Core Team

Contributors

Past Contributors

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.