MacRun Services

• Project Assignment Description
• Case Study (Fall 23): ACME Run
• MVP Report | Final Report

Contents

• Features
• Live Demo
  • Swagger API
• How to Build
  • Build (Micro-)services
• How to Deploy
  • Deploy Locally
• How to Use
  • With Simulator Script
  • With Postman
• How to Test
  • Auto Test
  • Manual Test

Features

• API Gateway (Caddy)
• Build Test CI (Actions)
• Health Check (Docker)
• Session Cache (Redis)
• Service Discovery (Nacos)
• Message Queue (RabbitMQ)

Live Demo

• Watch our demo video:

demo.mp4

• Feel free to use our demo services http://34.130.59.222:8080 on Cloud, so you don't have to build and deploy anything manually! e.g.:

pip3 install -U requests
python3 ./simulator-script/simulator.py 34.130.59.222:8080

Swagger API

These Swagger APIs are also available if you are deploying our services locally, and can be accessed at link http://127.0.0.1:8080/ with corresponding paths.

• Player Service: http://34.130.59.222:8080/player-swagger/index.html
• Game Service: http://34.130.59.222:8080/game-swagger/index.html
• GEO Service: http://34.130.59.222:8080/geo-swagger/index.html
• HRM Service: http://34.130.59.222:8080/hrm-swagger/index.html
• Challenge Service: http://34.130.59.222:8080/challenge-swagger/index.html

How to Build

Build (Micro-)services

We automatically build and push the image to DockerHub via GitHub Actions, so you don't need to build it locally. But if you want to build it anyway, please run the following command:

docker-compose build

How to Deploy

If you find that our service is a little slow (2~5 minutes) to start, this is normal. We have health check steps to ensure that each service is created and started properly before the API Gateway is launched.

Deploy Locally

If you are experiencing problems with our cloud services (the cloud can sometimes be a problem), or if you want to run our services completely on-premises, you can of course run the following command.

docker-compose pull && docker-compose up -d

How to Use

With Simulator Script

The script will simulate all actions like player registration, login, start heart rate monitor, start game, etc. It will also randomly generate heart rate, move random distance and react to game attacks.

• Please make sure you have Python3.8+ installed.
• Run the following commands in your shell:

cd ./simulator-script
python3 -m pip install -U requests
python3 ./simulator.py 127.0.0.1:8080

NOTE: If you start the services with a different address or port, you must change the 127.0.0.1:8080 parameter to your new service address.

With Postman

1. Import all postman collection files from postman-files.
2. Run the service APIs in Postman in the following order:
   • Player Register
   • Player Login
   • Player Set Zone
   • HRM Start
   • Game Start
   • Game Action
   • Game Stop
   • HRM Stop
   • Player Logout

NOTE: If you start the services with a different address or port, you must change the {{BASE_URL}} variable in each postman collection. The default value is http://localhost:8080.

How to Test

Auto Test

We automate the testing of our services using GitHub Actions CI. You can view the test results at:

• https://github.com/CAS735-F23/macrun-archless-team/actions/workflows/test.yml

Manual Test

If you want to run all the tests manually, go to each service folder and run test commands. Java and Golang environments are required to run the tests.

• Java Services, e.g. player-service:

cd ./player-service
mvn test

• Golang Services, e.g. game-service:

cd ./game-service
go test ./...