dublin2019 / api

Apache License 2.0
2 stars 1 forks source link
Build Status

Kansa

Kansa is a convention member management system originally developed for Worldcon 75, the World Science Fiction Convention organised in Helsinki in 2017. It is also used by Dublin 2019: An Irish Worldcon.

The system is modular and extensible. Together with its front-end client it provides the following services:

To help with at-con registration, Kansa has:

Specifically of interest to Worldcons, Kansa also provides:

Setting up and maintaining your own Kansa instance will require some experience with JavaScript and PostgreSQL. The front-end is a React app, while most of the back-end services run on node.js; the various parts are wrapped up in Docker containers. Work is ongoing to make the system more configurable and customisable, so fewer changes in code are required for convention-specific changes.

Getting Started

To get a dev environment up and running, first clone this repo. Then you'll need to have Docker Compose available, as that's used by default for container orchestration. To start, run make start or call docker-compose directly:

docker-compose \
  -f config/docker-compose.base.yaml -f config/docker-compose.dev.yaml \
  -p api up --build -d  # leave out the -d to not detach

Once you have all the services up and running, your development server should be available at https://localhost:4430/, including a relatively recent front-end client (with code hosted under GitHub Pages). You'll need to bypass your browser's complaint about the server's self-singed certificate:

The development server is bootstrapped with an admin account admin@example.com using the key key, which you may login as by visiting either of the addresses https://localhost:4430/login/admin@example.com/key (for smooth browser redicretion) or https://localhost:4430/api/login?email=admin@example.com&key=key (direct login, with JSON response).

Configuration

For production use and otherwise, the services' configuration is controlled by the Docker Compose config files. For development use, run make in the project root to include the base config docker-compose.base.yaml and the development config docker-compose.dev.yaml. For production use, the base config will instead need to be overridden by docker-compose.prod.yaml, which you will need to base on docker-compose.prod-template.yaml and fill with appropriate variable values (see make prod). Make sure that your production secrets are not committed to any repository!

For the most part, services are configured using environment variables, some of which need to match across services:

Email messages are based on message templates, which are documented separately.

Directory Overview

Kansa is Finnish for "people" or "tribe", and it's the name for our member registry. The Hugo Awards are awards that are nominated and selected by the members of each year's Worldcon. Kyyhky is Finnish for "pigeon", Raami is "frame", and Tuohi is the bark of a birch tree.

Common Issues

The particular places that may need manual adjustment are:


If you'd like to help with this project, please fell free to fork it and submit pull requests, or get in touch with us at kansa@maa-ilma.fi.