Chicago 2022 Worldcon / Bid Member Services API

This project was forked from the Worldcon75 code at https://github.com/worldcon75/api These are the back-end services used by the Chicago 2022 Worldcon Bid:

• docker-compose.* - Service configuration
• hugo - An express.js app providing the Hugo Nominations and Awards parts of the REST API
• kansa - An express.js app providing the core parts of the REST API
• kyyhky - Internal mailing service for hugo & kansa, using Kue
• nginx - An SSL-terminating reverse proxy & file server, using OpenResty
• postgres - Configuration & schemas for our database
• raami - An express.js app providing the Art show management part of the REST API
• tools - Semi-automated tools for importing data, and for other tasks
• tuohi - Fills out a PDF form, for people/:id/ballot

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.

For the front-end code, please see ChicagoWorldcon/client.

Getting Started

To get a dev environment up and running, first clone this repo with git clone --recursive, or run git submodule update --init after cloning. The database and server are set up to be run using docker-compose; for other tools you'll need a recent-ish version of node if you want to build them locally.

Here's a series of commands that should get the full working system installed and operational, provided that git, docker-compose and npm are already installed:

git clone --recursive https://github.com/worldcon75/api.git w75-api
cd w75-api
docker-compose 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 latest-release 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:

• Chrome: Click on Advanced, then Proceed to example.com
• Firefox: Click on I Understand the Risks, then Add Exception...., then Get Certificate, and finally Confirm Security Exception
• IE: Click on Continue to this website (not recommended)
• Safari: Click on Show Certificate, Always Trust "example.com" when connecting to "example.com", then Continue
• curl: Use the -k or --insecure flag to perform "insecure" SSL connections

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

Configuration

For production use and otherwise, the services' configuration is controlled by the Docker Compose config files. By default, docker-compose will include both docker-compose.yml and docker-compose.override.yml; the former acts as the base config, which the latter expands/overrides with development-specific configuration. For production use, the base config will instead need to be overridden by docker-compose.prod.yml (see make prod).

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

• JWT_SECRET and SESSION_SECRET allow the servers to share authenticated sessions
• DATABASE_URL and *_PG_PASSWORD are required for the services' database connections

Common Issues

The particular places that may need manual adjustment are:

• Connections to the server require TLS (HTTPS, WSS). For ease of development the repo includes a self-signed certificate for localhost. This will not be automatically accepted by browsers or other clients. If you have a signed certificate you can use (and therefore a publicly visible address), you'll want to add the certificate files to nginx/ssl/ and adjust the environment values set for the nginx service in docker-compose.override.yml and/or docker-compose.prod.yml.

• The CORS_ORIGIN variables in the docker-compose config files need to be space-separated lists of addresses at which client apps may be hosted, to allow for Cross-Origin Resource Sharing. By default, the value should match the http://localhost:8080 address of the client Webpack dev servers.

• If you're running the server on a separate machine or if you've changed the nginx port configuration, you may need to tell clients where to find the server, using something like export API_HOST='remote.example.com' before running npm start.

---

If you'd like to help with this project, please get in touch with us at [email protected]