https://github.com/bcgov/eagle-api
EPIC revision 2019
https://github.com/bcgov/eagle-api
api eao mongoose nodejs openshift rc-falcon-general
Last synced: 22 days ago
JSON representation
EPIC revision 2019
- Host: GitHub
- URL: https://github.com/bcgov/eagle-api
- Owner: bcgov
- License: apache-2.0
- Created: 2018-12-21T00:46:01.000Z (over 7 years ago)
- Default Branch: develop
- Last Pushed: 2026-05-12T02:36:39.000Z (25 days ago)
- Last Synced: 2026-05-12T02:39:12.074Z (25 days ago)
- Topics: api, eao, mongoose, nodejs, openshift, rc-falcon-general
- Language: JavaScript
- Homepage: https://projects.eao.gov.bc.ca/
- Size: 88.9 MB
- Stars: 5
- Watchers: 10
- Forks: 24
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# bcgov / eagle-api
[](https://github.com/bcgov/repomountie/blob/master/doc/lifecycle-badges.md)
API for acting as a central authenticated data service for all EPIC front-ends
## Documentation
All documentation has been consolidated in the [Eagle Documentation Wiki](https://github.com/bcgov/eagle-dev-guides/wiki):
* **[API Architecture](https://github.com/bcgov/eagle-dev-guides/wiki/API-Architecture)** - Service map, routing patterns, and request flow
* **[Configuration Management](https://github.com/bcgov/eagle-dev-guides/wiki/Configuration-Management)** - ConfigService pattern and environment variables
* **[Analytics Architecture](https://github.com/bcgov/eagle-dev-guides/wiki/Analytics-Architecture)** - Penguin Analytics integration
* **[API Deployment](https://github.com/bcgov/eagle-dev-guides/wiki/API-Deployment)** - Deployment workflows and procedures
* **[Deployment Pipeline](https://github.com/bcgov/eagle-dev-guides/wiki/Deployment-Pipeline)** - CI/CD workflows and image tagging
* **[Rollback Procedures](https://github.com/bcgov/eagle-dev-guides/wiki/Rollback-Procedures)** - How to rollback deployments
* **[Troubleshooting](https://github.com/bcgov/eagle-dev-guides/wiki/Troubleshooting)** - Common issues and solutions
## Related projects
Eagle is a revision name of the EAO EPIC application suite.
These projects comprise EAO EPIC:
*
*
*
*
*
*
*
* (rproxy reverse proxy)
* (analytics service)
## Quick Start
**Requirements**: Node 22.x, Docker
```bash
# 1. Install dependencies
yarn install
# 2. Configure environment
cp .env.example .env
# 3. Start MongoDB
yarn db:up
# 4. Start the API
yarn start
```
API available at `http://localhost:3000`
Swagger UI at `http://localhost:3000/api/docs/`
For watch mode (auto-restart on changes): `yarn start-watch`
To stop MongoDB: `yarn db:down`
## Deployment
For deployment procedures, Helm charts, and CI/CD workflows, see the [Deployment Guide](https://github.com/bcgov/eagle-dev-guides/wiki/Deployment-Pipeline) in the Eagle documentation wiki.
## Database
One can run the EPIC applications on two kinds of data; generated and backed-up-from-live.
Generated data will typically be cleaner as it is generated against the latest mongoose models. Generated data also does not require transferring PI to dev machines. Live production dumps should only be used in situations where a particular bug cannot be replicated locally, and after replicating, the data generators and unit tests should be updated to include that edge case.
#### Generate data
Described in [generate README](generate.md)
#### Restoring from a live backup
Acquire a dump of the database from one of the live environments.
To restore a dump into your local MongoDB:
```bash
# Drop the existing database (destructive!)
mongosh --eval 'use epic; db.dropDatabase()'
# Restore from a dump directory
mongorestore -d epic epic/
# Or restore from a gzipped archive
mongorestore --gzip --archive=epic-dump.tar.gz
```
#### Restore into the docker compose container (recommended)
With `yarn db:up` running, pipe a mongodump archive directly into the container:
```bash
# From a mongodump --archive file
yarn db:restore < epic-prod-dump.archive
# Or stream directly from a live environment
mongodump --uri="" --archive | yarn db:restore
```
The `db:restore` script runs `mongorestore --drop` inside the container, so it
replaces any existing data. The volume (`eagle-api_mongodb-data`) persists across
`yarn db:down` / `yarn db:up` restarts.
### Database Conversions
In the process of developing this application, we have database conversion scripts that must be run in order to update the db model so that the newest codebase can work properly. There are currently two methods of doing the database conversion depending on how long-lived and memory intensive the conversion is.
### Method 1: db-migrate
### Method 2: node scripts named migration* in the root folder
### Method 1
See for documentation on running the db migrate command. General use case for local development at the root folder:
```./node_modules/db-migrate/bin/db-migrate up```
For dev/test/prod environments, you will need to change the database.json file in the root folder accordingly and run with the --env param. See for more information.
### Method 2
In the root folder, there are files named migrateDocuments*.js. These are large, long-running, memory intensive scripts that operated on the vast majority of the EPIC documents. As a result, db-migrate was slow and unreliable given the nature of the connection to our database. As a result, these nodejs scripts operate using the mongodb driver in nodejs and can handle a more complicated, robust approach to doing the database conversion. They can be run from your local machine as long as there is a ```oc port-forward``` tunnel from your machine to the openshift mongdb database. Change the user/pass/port/host/authenticationDatabase params and the script will execute against the mongodb pod directly.
## Developing
See [Code Reuse Strategy](https://github.com/bcgov/eagle-dev-guides/dev_guides/code_reuse_strategy.md)
## Environment Variables
See `.env.example` for all available environment variables with descriptions and local defaults.
Key variables for local development:
- `KEYCLOAK_ENABLED=false` — disables Keycloak, uses local JWT with `SECRET`
- `MONGODB_SERVICE_HOST=localhost` — MongoDB host (default: localhost)
- `MONGODB_DATABASE=epic` — database name
Full reference: [Configuration Management](https://github.com/bcgov/eagle-dev-guides/wiki/Configuration-Management) wiki.
## Database Operations
### Enable MET Comment Periods for Project
1. Connect to Open Shift by copying login command
2. Choose project and get Pods
`oc get pods`
3. Port-forward
`oc port-forward eagle-api-mongodb-5-tj22g 5555:27017`
4. Connect to db with mongoshell
`mongo "mongodb://admin:pw@localhost:27017/epic?authSource=admin"`
5. Query for project
Eg. `db.epic.find({_id : ObjectId("65c661a8399db00022d48849")})`
6. Set `hasMetCommentPeriods` to `true` for the project.
Eg. `db.epic.updateOne( { _id: ObjectId("65c661a8399db00022d48849") }, { $set: { "legislation_2018.hasMetCommentPeriods": true } })`