Express API for the Smarter Balanced Content Specification Explorer

To get started, you need the following tools installed on your machine:

• Git
• Docker with docker-compose
• NodeJS (Current is preferred, LTS is fine)

Open your command-line tool of choice (cmd, Powershell, Terminal, etc.), and then run the following commands:

# Go to a directory of your choice
cd path/of/choice

# Clone the repository
git clone https://github.com/osu-cass/AP-CSE-API

# Enter the project directory
cd AP-CSE-API

# Install NPM dependencies
npm i

# Create a .env file for docker-compose to use
cp .env.example .env

With that, you should be able to start contributing.

The easiest way to run the server in development is to use the following command:

# Compile TS and watch the API server
npm run dev

This command will compile the Typescript sourcefiles and watch the dist output directory, recompiling and relaunching the server whenever you change a file. This launches the server without any associated databases.

If you're using VSCode, you can run the server with debugging using the Debug Server launch option. This will launch the server with nodemon so the server can autoreload on recompilation, and then attach a Node debugger on port 9222. For the best development experience, open a new CLI tab/window and run the following command:

# Recompile on file change
npm run watch-ts

Since this API server requires a number of resources for data storage and retrieval, we use docker-compose to run the following services for local development:

• MongoDB for document storage
• Elasticsearch for search indexing and log storage
• Logstash for log collection
• Jaeger for request tracing

We also run a few helpful applications to make development less painful:

• mongo-express for investigating the MongoDB instance
• Kibana for investigating the Elasticearch instance

Use the following table to figure out how to use each of these services in both the API and for debugging:

First, make sure that you have docker-compose installed:

docker-compose

If you get an error about being added to the docker user group, consult this issue on how to resolve it.

Then, you need to allocate more memory to Docker than the default amount. To do this, open your Docker preferences, open the Advanced tab, and move the Memory slider to somewhere around 3.5GB. Follow the steps that Docker requests once you save these changes.

Then, verify that you have a .env file in the root of the project. If you didn't make one during the project setup, do so now:

cp .env.example .env

The next steps are pretty simple. Run the following command in the root of the project to instanciate the services:

docker-compose up

The first run will take a decent amount of time, as Docker will do an initial build of the application image and pull down all the required service images. The output will more or less be a stream of logs, which you'll need to read through to figure out if anything fails. If all goes well, you should be able to visit localhost in the browser on the afore-mentioned exposed ports.

To enable file-watching and recompilation, run the following command in a seperate CLI instance:

npm run watch-ts

This will watch and rebuild the Typescript sourcefiles, and the instance of the API server in Docker will reboot itself using the new files.

In VSCode, we have a convenient launch configuration for debugging the server from within the Docker container. Simply launch the Attach to Docker launch configuration after you've followed the previous section, and VSCode will attach a debugger instance. With both the VSCode debug configuration and the watch-ts script running, you'll be able use breakpoints to debug the API server as you develop.

Building the deployment is fairly simple. You simply need to build the docker image and push the docker image to docker hub. You can do that by doing the following:

docker build -t {tag name} .
docker push {tag name}

For more information on deploying the CSE image please see the CSE configuration repository.