slotlist-backend

Backend of slotlist.info, an ArmA 3 mission planning and slotlist management tool.
The corresponding frontend implementation of this project can be found at slotlist-frontend.

Installation

Requirements

• Node 8.1 and up
• Yarn 1.4 and up
• PostgreSQL 9.6 and up

Package requirements

• libpq
• g++ (build only)
• make (build only)
• postgresql-dev (build only)
• python2 (build only)

Optional dependencies

• Docker 17.12 and up
• Docker Compose 1.14 and up
• Kubernetes 1.7 and up

Setup

Install and transpile TypeScript

$ yarn
$ yarn build

Prepare database and migrate to latest state

$ yarn migrate

Remove unneeded packages for minimal production install (optional)

$ yarn install --prod
$ yarn cache clean

Adjust required environment variables and config

Configuration will be parsed from environment variables, all of which can be found in the dev.env file as well as the Configuration markdown file in the docs/ folder of this repository.

Beside dev.env, you should create a .env file in the root of your repository - it will automatically be ignored by git. Use this file to overwrite the default config values or provide missing ones; you will at very least have to provide:

• CONFIG_STEAM_API_SECRET
• CONFIG_STORAGE_BUCKETNAME
• CONFIG_STORAGE_PROJECTID
• CONFIG_JWT_SECRET
• DEFAULT_ADMIN_STEAMID
• DEFAULT_ADMIN_NICKNAME

If you do not use Docker Compose to run slotlist-backend, make sure all environment variables are set up as listed in dev.env.

Usage

slotlist-backend can either be run "natively" or utilising Docker and Docker Compose.
When using the Docker Compose startup, a PostgreSQL instance will automatically be started as well, removing the need to provide a separate database setup.

Start with bunyan formatting

$ yarn start

Start with raw bunyan JSON logs

$ yarn start:docker

Start using Docker

$ docker-compose up

Development

The easiest way to start developing is by using the Docker setup as described above. Running docker-compose up automatically mounts the transpiled dist/ folder to the Docker container and watches for file changes - you can thus run a build task in your IDE and the backend container will automatically restart with the latest changes.

Unfortunately, there is no automated unit tests as of now (2018-01-09), however I plan on adding some mocha tests in the future, removing the need to test all new and existing functionality by hand.

Deployment

slotlist-backend was designed to be deployed to a Kubernetes cluster running on the Google Cloud Platform. The k8s/ folder contains the configuration files required to create and run all backend as well as other miscellaneous service and infrastructure. A cloudbuild.yaml file for automatic Docker image builds is provided in the repository root as well.

Generally speaking, slotlist-backend can be deployed anywhere running Node 8.1 or up and only depends on a PostgreSQL database.

Since no direct SSL support is integrated, we advise you to run the backend instance behind a reverse proxy such as nginx or traefik and handle SSL offloading there. Let's Encrypt provides excellent, free SSL certificates that are easy to integrate into your existing hosting, so there's no reason why you should run your site over plain HTTP!

Please be advised that some configuration values might need modifications should you plan to run your own instance since they have been tailored to work for slotlist.info's main instance. This is especially relevant for the CSP/HPKP headers set - failing to set these properly will result in problems loading your site.

Contributing

Pull requests are more than welcome - I am grateful for any help, no matter how small it is! For major changes, please open an issue first so proposed modifications can be discussed first.

All pull requests should be submitted to the dev branch - once a feature is fully implemented and tested, it will be merged to the master branch and deployed.
Attributions will be provided in the Contributors file inside the docs/ folder as appropriate.

In additional to development work for the backend or frontend projects, slotlist.info also needs your help in providing accurate and complete translations. We are utilising OneSky to crowd-source our translations and provide an easy interface to manage required strings. Feel free to contribute any translations or suggest a new language by opening an issue on the slotlist-frontend repository.

Versioning

slotlist-backend uses Semantic Versioning for releases, every deployment will be tagged with a new, appropriate version - old releases can be found on GitHub's release tab.

License

MIT

See Also

slotlist-frontend, the frontend portion of slotlist.info, written in Vue.js