diff --git a/README.md b/README.md index 5f824c1..136fecf 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,18 @@

-# 7th Cavalry ADR - +## Overview [![Server ADR Deployment](https://github.com/7Cav/adr/actions/workflows/server_adr_push.yml/badge.svg)](https://github.com/7Cav/adr/actions/workflows/server_adr_push.yml) [![Client ADR Deployment](https://github.com/7Cav/adr/actions/workflows/client_adr_push.yml/badge.svg)](https://github.com/7Cav/adr/actions/workflows/client_adr_push.yml) -## Overview - -This is a React application designed to display roster data fetched from the 7th Cavalry API. The project is structured as a client-server architecture and includes basic authentication for enhanced security. +The Active Duty Roster (ADR) is a Reactjs based app designed to automatically track membership of every position within the 7th Cavalry Gaming Regiment via the 7th Cavalry API. The ADR is structured as a client-server architecture and includes basic authentication for enhanced security. Though the ADR is accurate, semi-regular maintenence is needed in order to keep tracked billets up to date. ## Table of Contents - [Running Locally](#running-locally) - [Requirements](#requirements) - - [Authorization](#authorization) - - [Getting a Token](#getting-a-token) -- [Updating ADR](#updating-adr) + - [Authorization](#authorization) + - [Getting Started](#getting-started) +- [Updating the ADR](#updating-the-adr) - [Add New Billet in Existing Category](#add-new-billet-in-existing-category) - [Add New Category](#add-new-category) - [TODO](#todo) @@ -25,13 +22,53 @@ This is a React application designed to display roster data fetched from the 7th ### Requirements In order to run the ADR locally for development, you need the following: -- +- A valid [7th Cavalry Gaming](https://7cav.us/) account with member-level privileges (i.e. not a public account). +- An instance of [Node.js](https://nodejs.org/en) installed on your system. +- Your choice of IDE such as [VSCode](https://code.visualstudio.com/). + +#### Authorization + +Before you get started with your server, you require two methods of authentication. You require both an API token from 7th Cavalry Gaming and a local clientside token. + +To get and apply your API token do the following steps: + +1. Log into your 7th Cavalry Gaming account. +2. Navigate to your [Connected Accounts](https://7cav.us/account/connected-accounts/) and select the "view account" button for auth.7cav.us +3. Once you have logged into keycloak, copy the provided API token into your clipboard. +4. Open the adr project folder and navigate to `adr/server/credentials`. Inside should be a file named `example_token.js`. +5. Make a duplicate `example_token.js` and rename it to `token.js`. +6. Inside the new `token.js` file, paste your API token in the `API_TOKEN` constant and save the file. + +To make a clientside token, do the following: + +1. Open the adr project folder and navigate to `/client`. +2. Inside the Client folder create a nameless `.env` file. When opened, the directory should be `adr/client/.env` +3. Paste the following code into the `.env` file. + +```dotenv +REACT_APP_CLIENT_TOKEN ='XXXXXX' +REACT_APP_COMBAT_API_URL=http://localhost:4000/roster/combat +REACT_APP_RESERVE_API_URL=http://localhost:4000/roster/reserves +REACT_APP_CACHE_TIMESTAMP_URL=http://localhost:4000/cache-timestamp +``` +4. Replace the `REACT_APP_CLIENT_TOKEN` constant with a password of your choice and save. +5. Navigate to `adr/server/credentials/token.js` and ensure the `CLIENT_TOKEN` constant matches the same constant in the previous `.env` file and save. + +### Getting Started + +Before initializing the server, the dependancies for the ADR need to be installed on your end. + +- Open a terminal/cmd prompt and navigate to the adr project folder and execute the command `npm install`. +- Once the install finishes, navigate to `adr/client` and execute the previous command. + +You should now be ready to run the Server and the Client. -### Authorization +- Open two terminals. On the first terminal navigate to `adr/server` and enter the command `node server.js`. You should see that the server is listening on localhost:4000 and can be additionally verified by visiting localhost:4000 on your browser. +- On the second terminal, navigate to `adr/client/src` and run the command `npm start`. Once the clientside is running, you should be automatically redirected to localhost:3000 on your browser. A sucessful response is when the ADR is completely filled. -#### Getting a Token +You are now good to go! `adr/client/src/app.js` is the primary file in which everything on the clientside is ran. Closing the terminals will close the servers. Happy Coding! -## Updating ADR +## Updating the ADR ### Add New Billet in Existing Category @@ -104,6 +141,7 @@ const billetBank = { ## TODO +- [ ] Add tutorial for updating Statistics - [ ] Change cache warning on client to display time since cache refresh - [ ] Investigate the feasibility of sorting by rank after billet sorting (Subsorting? Consider using QuickSort) - [ ] Add graphical data visualization