The back-end services supporting HackIllinois 2017 are stored here.
We use Node.js + Express in the application layer. The MySQL RDBMS is used as our primary datastore in the persistence layer.
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.4.3. It is recommended that you install this version exactly, although using a different release version (v4.4.x) will probably work too.
The production-ready version of Node.js can be downloaded from here or from your favorite package manager.
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
commited to the project codebase, but changes to any *.config files are ignored.
A list of configuration options is provided below:
| Variable | Possible Values | Purpose |
|---|---|---|
| NODE_ENV | 'production' or 'development' | Determines how environment should be configured |
| HACKILLINOIS_SECRET | Any string | Sets the master secret (required on production) |
| HACKILLINOIS_PORT | Any valid port number | Overrides default port (8080) |
| HACKILLINOIS_SUPERUSER_EMAIL | Any valid email | Overrides the default superuser email ('[email protected]') |
| HACKILLINOIS_SUPERUSER_PASSWORD | Any string | Overrides the default superuser password ('ABCD1234!') |
| HACKILLINOIS_MAIL_KEY | Any string | Sets the mail service API key |
| DB_NAME | Any vaild SQL DB name | Overrides default MySQL DB name (hackillinois-2017) |
| DB_USERNAME | Any string | Overrides default MySQL username ('root') |
| DB_PASSWORD | Any string | Overrides default MySQL password ('') |
| DB_HOSTNAME | Any valid URI | Overrides default MySQL host ('127.0.0.1') |
| DB_PORT | Any valid port number | Overrides default MySQL port (3306) |
Additionally, an AWS shared credentials file
can be made available with configuration options for those systems under the profile
hackillinois-api. We do not handle AWS configuration options in our configuration files.
Not all configuration options must be set during development (although 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. Here are some considerations that will help you determine which keys to set as you develop:
- Anyone contributing to a feature that involves email transmissions
will need to set the
HACKILLINOIS_MAIL_KEYto a valid SparkPost API key. - Anyone contributing to a feature that involves any AWS products will need to set up an AWS shared credentials file (see above)
Note that this API is targeted for hosting via AWS, so any AWS-specific settings (e.g. those in IAM roles) are used by this API before settings in any environment variables or other credentials files.
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 schema called hackillinois-2017 on your local MySQL instance.
Once you have both of these tasks completed, run ./database/flyway.sh migrate
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.
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.
To run the API for development:
npm run dev
To run the API in production:
npm run prod
Use Control-C to kill the server. Note that node must be on your path and that
the configuration for the target environment must be present in the config directory.
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.