Skip to content

Latest commit

 

History

History
138 lines (101 loc) · 5.77 KB

DEVELOPMENT.md

File metadata and controls

138 lines (101 loc) · 5.77 KB
Raw

Jolly Roger development tips

Jolly Roger is written in TypeScript using the Meteor web framework (v2). To run Jolly Roger locally, first install Meteor.

Running a local server for development

Obtain the source code:

git clone https://github.com/deathandmayhem/jolly-roger
cd jolly-roger

Install dependencies from npm:

meteor npm install

Note

With Meteor, use meteor npm and meteor node instead of npm or node, to get the bundled version it needs.

Run Meteor:

meteor

This will start up a server on http://localhost:3000, which you can navigate to with your web browser of choice.

Running a production instance

To run Jolly Roger on a server for lots of people to use, see the Deployment and Monitoring documentation for Meteor. There are many ways to run the server, but they boil down to taking the tarball generated by meteor build, untarring it on some server, setting environment variables (see below), and running node main.js.

Important

Meteor v2 apps (like Jolly Roger) require Node.js v14, which is old and deprecated. If you're using a container, install that version. If you're running as a regular process, consider using a version manager like nvm, Volta, asdf or (my favorite) mise to avoid installing Node v14 globally.

You will also need some dependent services, at the very least a Mongo DB instance (for $MONGO_URL), some way to send email (for $MAIL_URL), a web server that can forward to your server and $PORT, and some domain name pointing to that web server (hopefully with an SSL certificate).

As a "canned configuration" for all of that, cloudformation/jolly-roger.yaml is a template for AWS CloudFormation. You will need to edit it for your use (change the domain name, etc) but then it can spin up a production system including Jolly Roger, a load balancer, a TURN server, SSL certificates, autoscaling and so on using Amazon Web Services. This configuration expects a database hosted elsewhere, like MongoDB Atlas.

Server environment variables

You can configure development and production Jolly Roger servers with a number of environment variables.

  • $CLUSTER_WORKERS_COUNT (cluster) - server process count, "auto" for the machine's core count, 1 by default.

  • $MAIL_URL (email) - an smtp:// or smtps:// URL for sending email, mostly for user signup. If your server has a self-signed TLS certificate, add ?tls.rejectUnauthorized=false to the URL.

  • $MONGO_URL (Meteor core) - the MongoDB server to use for storing Hunt and user data. This can be a server you run, or a server hosted on something like MongoDB Atlas. In development, a mini local MongoDB instance is set up for you.

  • $MONGO_OPLOG_URL (Meteor core) - the MongoDB operations log server to use for change monitoring. Strongly recommended for production, not needed for development. Requires the server to be a replica set (can be size 1). Typically this is the $MONGO_URL with /local replacing the Jolly Roger database name.

  • $PORT (Meteor core) - the socket port to listen for HTTP connections. Defaults to 3000. For dev, use --port=XXXX instead.

  • $ROOT_URL (Meteor core) - the base URL used to access your server. Not needed for dev servers.

  • $TURN_SERVER - the URL of a TURN server for robust audio chat connectivity.

  • $TURN_SECRET - the secret needed to authenticate with $TURN_SERVER.

Also see the other environment variables defined by Meteor core and other packages.

Setting up a fresh Jolly Roger server

When you start a server with an empty database (development or production), the server will initialize itself but you have to do some setup steps in the web interface.

Admin account creation

Loading the Jolly Roger web interface for the first time will prompt you to create a user with the admin role and log you in as that user. Once that's done, you can begin using Jolly Roger, invite other users and so on.

Server options and integrations

Users with the admin role can configure other server options from the setup page (look for "Server setup" in the user pulldown menu in the upper right). This is where you configure integration with Google, Discord, etc.; the page walks you through the steps to generate the required keys and such.

Example hunt data

Jolly Roger ships with a fixture representing data from the 2018 MIT Mystery Hunt, to get a sense of what a fully-populated UI might look like.

If you haven't yet created any hunts in your Jolly Roger instance, then you can load the homepage (click the logo in the upper left) and click the "Create sample hunt" button. Otherwise, you can open the browser javascript console (not the Meteor shell) and run the following:

Meteor.call("Hunts.methods.createFixture");

Either way, upon success, you should see a hunt named "Mystery Hunt 2018" in the list on the homepage.