STAIR Houses

Displaying and editing STAIR Houses points on the web.

About The Project

This project is used to display and edit the current points total of the STAIR "houses".

It provides a public website to view the scores as well as a password protected admin panel to add and remove points.

The project consists of a frontend as well as a backend which the frontend connects with and where the points are stored.

The frontend is deployed here.

Built With

This project is build with modern web-technologies, the most important are:

Frontend

• Vue.js 3 (Composition API)
• Vite
• SCSS/Sass
• Vue Router

Shared / Both

• Typescript
• tRPC
• WebSockets
• RxJS

Backend

• Node.js
• fastify
• MongoDB

Getting Started

To set up the project locally follow the following steps.

Prerequisites

To install and run the project you will need the following:

General / Shared

• Git: install (click here)

• a recent version of Node.js and npm: install (click here), update:

  npm install npm@latest -g
  npm install -g node

• Yarn v1.x (not 2): install instructions or use

  npm install --global yarn

Backend

• MongoDB: install (click here)

Frontend

• A (or better multiple) modern browser(s)

Cloning and installation

1. Clone the repo

   git clone git@github.com:stairch/stair-houses.git

   or

   git clone https://github.com/stairch/stair-houses.git

2. Enter the directory

   cd stair-houses

3. Install NPM packages at root level (This will install husky for commitlint.)

   yarn

Subprojects installation and running (easy helper scripts)

To install and run the subprojects using the helper scripts (from the root level) use the following commands.

1. Install NPM packages for all subprojects

   yarn install:all

2. Start the backend and the frontend with auto-recompile, auto-restart and auto-refresh on changes (no type checking in the frontend)

   yarn serve

   or build the backend and the frontend completely once (includes type checking in the frontend and will use the production configuration for the frontend)

   yarn build

3. Format everything using linters (includes lint check after formatting each subproject)

   yarn format

   or only lint it

   yarn lint

Subprojects installation and running (manual)

To install and run the subprojects manually use the following commands.

Frontend

1. Enter the directory

   cd frontend

2. Install NPM packages for the frontend

   yarn

3. Start Vite with auto-recompile and auto-refresh on changes (no type checking)

   yarn dev

   or build it completely once (includes type checking and will use the production configuration)

   yarn build

4. Format using linters

   yarn format:all

   and lint it afterwards

   yarn lint:all

Backend

1. Enter the directory

   cd backend

2. Install NPM packages for the backend

   yarn

3. Run typescript with auto-recompile on changes

   yarn watch

   or build it once

   yarn build

4. Open a new shell instance/terminal and navigate to the same location

   cd backend

5. Run the program with Node.js and auto-restart on changes

   yarn serve

   or run it once

   yarn start

6. Format using linters

   yarn format:all

   and lint it afterwards

   yarn lint:all

Configuration, building and deployment

This project is configured by default to run on localhost and in development configuration. To configure and build it for production, set the following environment variables:

Frontend

VITE_STAIR_HOUSES_PROTOCOL="wss"
VITE_STAIR_HOUSES_BACKEND_HOST="<domain>"
VITE_STAIR_HOUSES_BACKEND_PORT="3033"
VITE_STAIR_HOUSES_CAPTCHA_SITEKEY="<hCaptcha sitekey (can be omitted to disable captcha)>"

These can be set in a .env.production.local file in the frontend directory so they will be used for every full build (using yarn build), but not for testing and development. (Or create a .env file to also use it while testing and development.)

In the frontend the environment variables will be loaded in at compile/build time an can therefore be omitted when deploying the compiled/built dist files on a webserver.

Backend

STAIR_HOUSES_PORT="3033"
STAIR_HOUSES_IP="<server IP address, NOT DOMAIN!!!>"
STAIR_HOUSES_SSL_CERT="<file path to ssl certificate (can be omitted, then http/ws will be used)>"
STAIR_HOUSES_SSL_KEY="<file path to ssl private key (can be omitted together with the certificate)>"
STAIR_HOUSES_FRONTEND_HOST="stair.ch"
STAIR_HOUSES_DEFAULT_PASSWORD="<default password to be set on first connection to database, if not set already, SHOULD BE REMOVED/OMITTED LATER!!!>"
STAIR_HOUSES_DATABASE_HOST="localhost"
STAIR_HOUSES_DATABASE_PORT="27017"
STAIR_HOUSES_DATABASE_USER="<MongoDB user (can be omitted)>"
STAIR_HOUSES_DATABASE_PASSWORD="<MongoDB password (can be omitted)"
STAIR_HOUSES_CAPTCHA_SECRET="<hCaptcha secret (can be omitted to disable captcha)>"

These can also be set in a .env file in the directory it's run from. WARNING: Unlike in the frontend, they will be used for every run (including testing and development). They are not needed at compile time and can be omitted for most testing and development setups.

Since the environment variables will be loaded at runtime they need to be included when deploying the compiled dist files on a server.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Important: To keep this project clean and easily readable, we use conventional commits and an entire suite of linters. Before submitting your Pull Request, check that you have followed conventional commits and run the format and lint commands mentioned above.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feat/add-amazing-feature)
3. Commit your Changes (git commit -m 'feat: add some amazing feature')
4. Push to the Branch (git push origin feat/add-amazing-feature)
5. Open a Pull Request

License

Distributed under the GNU General Public License v3.0. See LICENSE for more information.

(back to top)