The back-end services supporting HackIllinois 2017 are stored here. Looking to contribute? See the contribution guidelines.

We use Node.js + Express in the application layer. The MySQL RDBMS is used as our primary datastore in the persistence layer. The Redis store is used as our primary cache.

If you are a front-end developer that wants to use a local instance of the API or someone who just wants to run the API for novelty, the most-accessible major releases of the following software will likely work for you.

These version notes are more important for back-end developers who will be committing code to this repository.

Our application is deployed with Node.js v4.6.2. It is recommended that you install this version, although using a different release version (v4.6.x) will probably work too.

The production-ready version of Node.js can be downloaded from here.

Our primary datastore is deployed MySQL 5.7.11. Again, it is recommended that you install this version exactly, although we typically use a different release version (5.7.x) during development.

The production-ready version of MySQL is not typically available for direct download, although some mirrors may have this version available. Instead, it is sufficient to get the latest 5.7.x download from here or from your favorite package manager.

The API is configured using configuration files placed in the config directory. The naming convention is {ENV}.config, where {ENV} is the target environment (like dev or prod).

We have provided templates in the directory already with all available configuration options. These templates are named {ENV}.config.template. You should copy these templates into files named {ENV}.config and fill them with sensible values; these values can be raw values or existing environment variables. Note that changes to the templates are committed to the project codebase, but changes to any *.config files are ignored.

A list of configuration keys is provided below:

Additionally, an AWS shared credentials file can be made available with configuration options for those systems under the profile identified by hackillinois-api. Be sure to set the AWS configuration key to 1 and add the key AWS_PROFILE to your configuration with your corresponding profile name.

Not all configuration options must be set during development (but all options should be set in production). When certain keys are left empty, the API determines whether or not it can use a local alternative or a default value at startup.

A typical package.json is present in the root of the project directory. You can use it to install all of the dependencies at once by running the following:

npm install

Note that your current directory must be the root of the project.

To begin, you will need the FlywayDB command line tool. Further, you'll need to create a new schema for the API on your local MySQL instance. Make sure that all configuration keys related to the database have the correct values!

Once you have both of these tasks completed, run npm run dev-migrations from the root of the project directory. This will run all migration scripts available to-date. If you see any errors, such as an inability to access the database, make sure you have set up the schema correctly and that you have set any necessary MySQL environment variables listed in the configuration section above.

You should also have a local Redis instance which will be used as the cache.

Note that if you're looking to contribute to this codebase, you should read the database README as well. It contains important information that all contributors should be familiar with.

A local API instance can be created on port 8080 via the following commands, executed from the root of the project directory. Note that in development, you must to install the process manager nodemon globally via [sudo] npm install -g nodemon.

To run the API for development:

npm run dev

Note that node must and nodemon must be on your path and that the configuration for the target environment must be present in the config directory. The server will restart automatically when changes are made. To stop the API, simply type Control-C.

For production, we build a Docker image and deploy this to a container ecosystem. You can find the Dockerfile in the project root directory.

The API access logs are available in /temp/logs/api.log as well as on the console during development. In production, the logs are periodically pushed to AWS CloudWatch (and are not accessible until they are pushed). Note that the logs (excluding those on the console) are optimized for searchability, not readability.

You can clean up the file logs during development by running

npm run clean-logs

All documentation is available on the project wiki.

Please use the issue tracker to submit issues about features currently in master or staging.

Any issues found in a feature branch (i.e. not in master or staging) should be communicated to the active developer(s) directly, unless there is an open pull-request for that feature branch. In the latter case, just leave a comment on the pull-request detailing the issue preventing a merge.

Environment variables should be set in test.config. With these values set, run

npm test