Node.js REST service for the BadgeHub
In order to make sure that we can keep track of the database schema, we use db-migrate. This allows us to track the database changes along with git and provide a framework for migrating data and rolling back changes. So when a change to the database schema is needed, a new migration should be created instead of manually changing the database. To create a new migration, follow the steps below.
npm run db-migrate:create -- <migration-name>
This will create a new migration file in the migrations
directory with the name <timestamp>-<migration-name>.js
as well as 2 sql files, one for the up migration and one for the down migration.
These sql commands should take care of changing the database schema as well as migrating the data if necessary.
npm run db-migrate:up
For the mock data, we always want up to date tables. So if you change something to the database, you should also update the population script and then you should run it from the server:
curl -X POST http://localhost:8081/dev/populate
This script will also automatically update the mockup-data.sql
file after completion.
Note that this mockup-data.sql
is not completely deterministic, so it might not be the same every time you run it.
The actual table data should be deterministic though, it's just that the dumping can decide to dump the data in a slightly different order.
To keep the determinism of the actual table content after repopulation, we do the following:
- we reset the primary key sequence for each table after clearing the table at the start of the script
- we use mock dates for the
created_at
andupdated_at
fields, so that the dates don't change when running the population script twice.
npm run db-migrate:down
When the code is deployed, the up migrations will be run automatically before starting the server.
Make sure Docker is installed and running.
Before running, copy the .env.example
into .env
cp .env.example .env
and fill out the details.
Then start the Docker containers by typing
docker compose up --detach
Then visit http://localhost:8001/ for the development BadgeHub homepage.
Visit http://localhost:8002/ for the pgAdmin interface.
Use password badgehub
to connect to the BadgeHub database server.
Use the OpenAPI (Swagger) documentation to interact with the REST API.
After setting up the development container, you can start it with
docker compose up --detach
The API should now be accessible through localhost:8001
.
And to stop BadgeHub
docker compose down
Or, to stop BadgeHub and delete all volumes (to start fresh)
docker compose down --volumes
Container commands like stop
, start
, restart
and logs
can also be sent to one of the containers from the compose file. For example
docker compose restart node
will restart the node container only.
At the moment, this is the database schema:
In production, use the production docker compose file docker-compose.production.yml
.
The NODE_ENV
environment file is set to production
, there's no watcher and
PM2 is used to run Node.js multithreaded.
The first time, a Docker container is created. Make sure the dist
directory
contains the latest build to be copied to the container.
Also the public
directory and package.json
and package-lock.json
will
be copied.
To start:
docker compose --file docker-compose.production.yml up --detach
Then visit http://localhost:9001/ for the production BadgeHub homepage and http://localhost:9002/ for PG_Admin, the UI for the database.
To wind down:
docker compose --file docker-compose.production.yml down
- Express, a framework for Node.js
- tsoa for generating a swagger file from code
- sql-template-tag for more easily writing SQL queries
- db-migrate for database migrations
- tsx for watching TypeScript files in Node.js
- PM2 for managing Node.js processes