Worldcon 75 Member Services

This project is under active development, so not everything is ready yet. The main components are:

• client - The client front-end for our membership; a react + redux single-page app
• docker-compose*.yml - Service configuration
• hakkapeliitta - A deprecated Scala webshop implementation, due to be ported to node.js
• hugo/server - An express.js app providing the /api/hugo/ parts of this API
• kansa/server - An express.js app providing the /api/kansa/ parts of this API
• kansa/importer - A tool for importing CSV & JSON data from our prior registry format
• kansa/admin - An internal front-end for the registry data; a react + redux single-page app
• kyyhky - Internal mailing service for hugo & kansa, using Kue
• nginx - An SSL-terminating reverse proxy for Kansa
• postgres - Configuration & schemas for our database

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".

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
cd client
npm install && npm start

Once you have all the services up and running, first visit https://localhost:4430/ in your browser to trigger its complaint about the server's self-singed certificate, and bypass it:

• 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

Once that's done, visiting http://localhost:8080/ should redirect you to the login page, where the bootstrapped admin account is available as email [email protected], and key key. Visiting the address http://localhost:8080/#/login/[email protected]/key should also automatically log you in.

Currently, kansa/admin is set up to run completely separately from client, but using the same server address http://localhost:8080/. To use it, it may be easier to login first using client, or by visiting the API endpoint https://localhost:4430/api/kansa/[email protected]&key=key to set the proper auth cookie.

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:

• SESSION_SECRET allows hugo/server and kansa/server to share authenticated sessions
• DATABASE_URL and *_PG_PASSWORD are required for the services' database connections

The production config includes the client-build service, which is used to build the client's JS assets, which are then served by nginx.

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 hugo/server/dev.env and kansa/server/dev.env need to be space- or comma-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 and kansa/admin Webpack dev servers started by npm start in each directory.

• 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. The default is set here to localhost:4430' or the address of your Docker VM.

---

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