Boardr

A distributed web application to play board games.

• Disclaimer
• Contents
  • HTTP API backend
  • Single-page application frontend
  • Load testing
  • Local Vagrant environment
  • Raspberry Pi cluster
• Requirements
  • Runtime
  • Database
• Development
  • Backend
  • Frontend
• TODO
  • Documentation
  • Roadmap

Disclaimer

This repository is a work in progress. It contains a pile of unholy experiments on my journey to learn Elixir and Elm, and to try to make things fit together that should not. It barely holds together. Do not, under any circumstances, take any of this code within one hundred feet of any production system. You have been warned.

Contents

The mess in this repository.

HTTP API backend

The server directory contains the application's backend written in Elixir.

• The application is an Elixir Umbrella project split into a "business" application in server/apps/boardr and the HTTP API in server/apps/boardr_api.
• The HTTP API is a hypermedia REST API using the HAL+JSON format.
• Errors are intended to be in the standard format described by the Problem Details for HTTP APIs RFC, although all error handling in this project is a work in progress.

Single-page application frontend

The client directory contains the application's frontend written in Elm.

Load testing

This repository contains a load-testing scenario for the application, written with Locust.io.

• The code is in the load-testing directory.
• You may set up a local test using Docker and Docker Compose by running ./scripts/load-testing.sh.

Local Vagrant environment

WARNING: this environment may not fully work.

A Vagrantfile to run the application in a local virtual machine with Vagrant.

• Requires Vagrant, VirtualBox and Ansible.

• Microk8s is installed on the virtual machine to run the application in a Kubernetes cluster. The Ansible roles that do this are in the k8s directory.

• Define the following hosts in your /etc/hosts file:

  192.168.50.4 boardr.vagrant
  192.168.50.4 locust.boardr.vagrant
  192.168.50.4 traefik.boardr.vagrant
  

• Note: the Kubernetes configuration in the k8s/config directory must be manually loaded from inside the virtual machine using the kubectl command. The directory is available inside the virtual machine at /vagrant/k8s/config.

Raspberry Pi cluster

An Ansible playbook to run the application in a distributed cluster of Raspberry Pi single-board computers.

• The Ansible playbook and roles are in the cluster directory.

• Requires Ansible and at least 4 Raspberry Pi computers.

• The cluster can be simulated in local virtual machines using Vagrant and VirtualBox. Use Vagrant from the cluster directory.

  • Define the following hosts in your /etc/hosts file:

    192.168.50.5 boardr.cluster.vagrant
    

• Copy cluster/inventory.vagrant.yml to cluster/inventory.yml and use that inventory to deploy the application to your own cluster. The configuration assumes each Raspberry has a fixed IP address.

  • Define the following hosts in your /etc/hosts file (assuming 10.0.1.100 is the Raspberry Pi on which the reverse proxy is running):

    10.0.1.100 boardr.cluster
    

Requirements

Runtime

As described in .tool-versions:

elixir 1.10.0-otp-22
elm 0.19.1
erlang 22.2.3
nodejs 12.14.1

Run asdf install with asdf to install everything.

Tested on macOS 10.14 & 10.15.

Database

• PostgreSQL 12.x

Development

Backend

Create server/config/env.exs with the following contents:

use Mix.Config

config :boardr, :options,
  client_id: "GOOGLE_CLIENT_ID",
  client_secret: "GOOGLE_CLIENT_SECRET"

config :boardr, Boardr.Auth,
  secret_key_base: "CHANGE_ME_TO_A_VERY_LONG_RANDOM_STRING"

Migrate the database:

mix ecto.migrate

The application will attempt to connect to the boardr database through the PostgreSQL Unix socket by default. Set $BOARDR_DATABASE_URL or $DATABASE_URL if your setup is different (e.g. ecto://boardr:changeme@localhost:5432/boardr).

Run the server in development mode:

cd backend
mix phx.server

Open http://localhost:4000/api.

Frontend

cd frontend
npm ci
npm start

Open http://localhost:8000.

TODO

Documentation

• There are working Dockerfiles in server which should be documented.
• Document commands to set up the other environments (production, docker, load testing, Vagrant, cluster).

Roadmap

• Use WebSocket, because an HTTP API for a web game was a bad idea to begin with (duh).
• See if Locust can be coerced into testing a non-request-response-based WebSocket API, or find another load testing tool.
• Find more things that don't fit to shoehorn into this project.