π Let's make the Helpdesk System great again!
π This project is in early development - Expect constant changes.
π The wiki page on this repo holds the dokumentation for this project.
π€ The discussions page is the perfect place to chat with others about the project and propose new ideas or features.
π£ Here you can also find announcements about the projects progress.
The issues page is for anyone to report
- πΎ Bugs (obvious errors that compromises the systems functionality).
- π² Concerns (other types of errors that compromises the systems efficiency or usability).
π¨βπ» This project is developed using Node js (Express js), MariaDB and React
For specific information about the technologies version, see the package.json for the frontend and the package.json for the backend.
The project is divided into 2 main folders:
- Node js - The backend is written in Node js, so you need to have Node js, installed on your machine.
- NPM - The frontend and backend both use npm to manage dependencies, which is installed with Node js by default.
- MariaDB - The database is written in MariaDB, so you need to have MariaDB installed on your machine.
- Git - The project uses Git for version control, so you need to have Git installed on your machine.
The project uses environment variables to store sensitive information. You need to create a .env file in the root folder of the project. In the root folder we've included a .env.example file that you can use as a template.
The .env file for the backend should look something like this:
NODE_ENV="development" #Nodejs environment. Format: "development" or "production".
DATABASE_URL="database_url" #URL to the database. Format: "mysql://user:password@host:port/database".
FRONTEND_URL="http://localhost:5173" #URL to the frontend. Format: "http://localhost:port,http://localhost:port2".
BACKEND_PORT=3000 #Port the backend should run on. Default: 3000
JWT_SECRET="secret" #Secret used to sign the JWT tokens.
LDAP_HOST="xxx.xxx.xxx.xxx" #IP address of the LDAP server. Format: "xxx.xxx.xxx.xxx".
LDAP_PORT="389" #Port of the LDAP server.
LDAP_USERNAME="username" #Username used to connect to the LDAP server.
LDAP_PASSWORD="password" #Password used to connect to the LDAP server.
LDAP_BASE_DN="base_dn" #Base DN of the LDAP server.
LDAP_USERS="users" #DN of the "regular" users (non-admin) in the LDAP server.
LDAP_ADMINS="admins" #DN of the admins in the LDAP server.
MAIL_MAILER="mailer" #Mailer used to send emails.
MAIL_HOST="host" #Host of the mail server.
MAIL_PORT=587 #Port of the mail server.
MAIL_USERNAME="username" #Username used to connect to the mail server.
MAIL_PASSWORD="password" #Password used to connect to the mail server.
MAIL_ENCRYPTION="tls" #Encryption used to connect to the mail server.
MAIL_FROM_ADDRESS="from_address" #Email address used as the sender of the emails.
MAIL_FROM_NAME="from_name" #Name used as the sender of the emails.
The .env file for the frontend should look something like this:
VITE_APP_BACKEND_URL="http://localhost:3000/api"
- Inside VS code, press "Clone git repository..." and paste the link to this repository. repo link.
You need to have Git installed on your machine for this to work.
- Choose a location on your machine to clone the repository to.
- Open the folder in VS code.
- Open a terminal in VS code in the backend folder.
- Run
npm run i
to install the frontend dependencies.
You need to have Node.js installed on your machine for this to work. Watch out for errors in the terminal. If that happend try reading the error message and resolve the issue.
- Open a terminal in VS code in the backend folder
- Run
npm run dev
to start the backend server.
You need to have Node.js installed on your machine to run the backend.
- Open a terminal in VS code in the root folder.
- Run
npm run i
to install the frontend dependencies.
You need to have Node.js installed on your machine for this to work. Watch out for errors in the terminal. If that happend try reading the error message and resolve the issue.
- In a root folder terminal, run
npm run dev
to start the frontend server. Or runnpm run host
to expose the frontend server to the network. - Open the link provided in the terminal to open the frontend in your browser. Typically its gonna be hosted on http://localhost:5173.
You need to have Node.js installed on your machine to run the frontend. If the frontend crashes or behaves strangely, the backend is probably not running or the .env file has incorrect values.
π You now have the project up and running on your machine (hopefully). You can now start developing on the project.
π We welcome contributions to this project. To contribute, speak with a teacher and get the necessary permissions and secret variables. Then follow the steps below.
- Press the fork button in the top right corner of the repository page.
- Choose your account as the destination for the fork.
- Clone the forked repository to your machine.
You need to have Git installed on your machine for this to work.
- Open the repository in VS code.
- Press the branch button in the bottom left corner of VS code.
- Press the plus button to create a new branch.
- Name the branch after the feature you are working on.
- Make the changes you want to make.
- Commit the changes to the branch you created.
- Push the changes to the branch you created.
- Go to the original repository page.
- Press the pull request button.
- Press the new pull request button.
- Choose your forked repository as the source.
- Choose the branch you created as the source branch.
- Choose the main branch as the destination branch.
- Press the create pull request button.
- Name the pull request after the feature you are working on.
- Press the create pull request button.
- Wait for a teacher or the repo owner to approve your pull request.
- If the pull request is not approved, make the necessary changes and push them to the branch you created.
- When the pull request is approved, press the merge pull request button.
- Press the confirm merge button.
- Press the delete branch button.
π You have now contributed to the project. Your changes will be included in the next release of the project.
- YOU ARE NOT ALLOWED TO PUSH SENSITIVE INFORMATION TO THE REPOSITORY.
- YOU MUST NEVER EDIT GITHUB ACTIONS BECAUSE THEY CAN ACCESS SENSITIVE INFORMATION.
- YOU MUST NEVER PUBLISH THE .env FILE TO THE REPOSITORY.
- You are not allowed to push directly to the main branch.
- You are not allowed to merge your own pull requests.
- You are not allowed to approve your own pull requests.
If any of these rules are broken, the pull request will be denied.