Displaying and editing STAIR Houses points on the web.
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.
This project is build with modern web-technologies, the most important are:
To set up the project locally follow the following steps.
To install and run the project you will need the following:
-
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
- MongoDB: install (click here)
- A (or better multiple) modern browser(s)
-
Clone the repo
git clone git@github.com:stairch/stair-houses.git
or
git clone https://github.com/stairch/stair-houses.git
-
Enter the directory
cd stair-houses -
Install NPM packages at root level (This will install husky for commitlint.)
yarn
To install and run the subprojects using the helper scripts (from the root level) use the following commands.
-
Install NPM packages for all subprojects
yarn install:all
-
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
-
Format everything using linters (includes lint check after formatting each subproject)
yarn format
or only lint it
yarn lint
To install and run the subprojects manually use the following commands.
-
Enter the directory
cd frontend -
Install NPM packages for the frontend
yarn
-
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
-
Format using linters
yarn format:all
and lint it afterwards
yarn lint:all
-
Enter the directory
cd backend -
Install NPM packages for the backend
yarn
-
Run typescript with auto-recompile on changes
yarn watch
or build it once
yarn build
-
Open a new shell instance/terminal and navigate to the same location
cd backend -
Run the program with Node.js and auto-restart on changes
yarn serve
or run it once
yarn start
-
Format using linters
yarn format:all
and lint it afterwards
yarn lint:all
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:
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.
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.
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.
- Fork the Project
- Create your Feature Branch (
git checkout -b feat/add-amazing-feature) - Commit your Changes (
git commit -m 'feat: add some amazing feature') - Push to the Branch (
git push origin feat/add-amazing-feature) - Open a Pull Request
Distributed under the GNU General Public License v3.0. See LICENSE for more information.