hack-week-generator

Contains clojure source code which comprises the following assets:

• hack-week-generator-api - a web service that provides recommendations and representations for learners
• hack-week-generator-introspect - a single page application that can be used to interrogate the voila-api
• hack-week-generator-microapp - a (potential) single page application that integrates with Cambridge One

Currently we host the hack-week-generator-introspect web app under /internal/app of the hack-week-generator-api although it's a goal of the project to have all three elements be highly decoupled.

Contains terraform configuration for managing other related infrastructure here terraform.

Contains GitHub Actions for configuring Continuous Integration and Continuous Deployment here .github/workflows.

Required Software & Configuration

• For development you'll need to be able to clone from/push to github instructions here

• For interacting with AWS you'll need to have keys set in your environment instructions here

MacOS

For developing the hack-week-generator-api service:

brew install leiningen

For developing the hack-week-generator-introspect webapp:

brew install npm
npm install -g shadow-cljs

For building infrastructure:

brew install terraform

For deployment:

brew install aws/tap/copilot-cli
brew cask install docker

Developing

hack-week-generator-api

You should be able to start a development repl with:

lein repl

And run:

=> (start-server 9000)

For the service we're preferring metosin where they exist for a given problem as they are reliably amongst the most reliable and offer the most leverage based on the code we write.

Libraries that are useful for understanding the service:

• reitit - Documentation
• clojure/spec - Getting Started - API Docs

hack-week-generator-introspect

For hack-week-generator-introspect we're building our application using shadow-cljs, creating a react frontend with reagent and taking advantage of the excellent evergreen component/UI react framework.

It can be complicated to run all of these parts together but hopefully once you're up and running you can see the benefit each part brings.

To get started make sure you've installed the dependencies listed above (a bare minimum would be a working copy of npm).

First, make sure we have npm dependencies:

npm install

Then trigger shadow-cljs to build us an index.js binding:

npx shadow-cljs watch client

And then in a separate, terminal window run this:

npx webpack --mode development --watch target/index.js --output public/js/libs.js

Testing

See the section on Continuous Integration

hack-week-generator-api

You can run the tests for hack-week-generator-api with

lein test

Deploying

See the section on Continuous Deployment

We use aws-copilot to deploy new versions of the hack-week-generator-api. It currently depends on building and sending a docker image based on the current dockerfile in the repository deploying with:

copilot svc deploy # detailed configuration can be found at `scripts/deploy.sh`

Infrastructure

We use aws-copilot to manage infrastructure for running hack-week-generator-api. By convention it is running on AWS Fargate via AWS ECS.

Configuration for the copilot deployment can be found in the copilot directory.

Continuous Integration

We're using github actions to build, test and deploy software.

Continuous Deployment

When you push to or merge changes into master an action will automatically release and deploy a new version.