include_toc
true

Table of Contents

• CSIS Equipment Booking System - How to review and run the application
• Important note:
• Quick Start Guide
• Prerequisites
• Setting Up Environment Variables
• Running the Application
• Accessing the Application
• Checking Service Status
• Stopping the Application
• Default Admin Credentials
• Troubleshooting
• Project Base
• Tools
• Kanban
• CI/CD
• Components
• README.md
• LICENSE
• .gitignore
• .gitattributes
• .forgejo/workflows/check_lfs.yaml
• Github compatability
• Directories
• src
• doc
• Useful but less important
• .mailmap
• .gitkeep
• Updating

CSIS Equipment Booking System - How to review and run the application

Important note:

Since commits that have been made after 7:30 cannot be considered (other than this documentation itself), if this repo's state at 7:30 is what's being used to review the code, then the dev branch should be the one that's reviewed, as its code would have been the most up to date at that time, and was the one that we used when demonstrating the system we created.

The change we made after the 7:30 deadline between these branches was simply changing the dev branch to be named main, and make that new main branch the default branch, such that it will be more clear where the correct code is located, so that could also be pulled for convenience to run the application. But if the 7:30 deadline is to be enforced strictly, then the dev branch at that time should be the one that gets pulled to review the code and run the application.

To summarise, if the repo's state before 7:30 is being used -> pull from the dev branch, if the repo's most recent state regardless of that deadline is being used -> pull from the main branch.

Quick Start Guide

This guide will help you get the lab equipment booking system up and running on your local machine. The project uses Docker Compose to manage all services, so you'll need Docker and Docker Compose installed before proceeding.

Prerequisites

Before you begin, ensure you have the following installed:

• Docker Desktop (or Docker Engine with Docker Compose)
• A text editor or IDE for editing configuration files

Setting Up Environment Variables

The application requires a .env file in the project root directory with the following variables:

• SUPABASE_PASSWORD - Your Supabase database password
• SUPABASE_URL - Your Supabase project URL
• SUPABASE_KEY - Your Supabase API key

We didn't commit this file to the repo for privacy reasons. We can send this .env file across email if contacted for it so that when the system is being run, it will be able to use the values from our demo database.

If you want to set up the system with a fresh Supabase database instead, you can create a new Supabase project and use its credentials in your .env file. The system will automatically create the initial admin account (admin@ul.ie) when the backend starts for the first time, so no manual database setup is required beyond providing the database connection details.

Create a .env file in the root directory and add these variables with your actual values. If you don't have a .env file yet, create one based on the example below:

SUPABASE_PASSWORD=your_database_password
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_api_key

Running the Application

Once you have your environment variables configured, you can start all services with a single command:

docker compose up --build -d

This command will:

• Build the Docker images for the backend and frontend
• Start all required services (backend, frontend, Redis, RabbitMQ)
• Run everything in detached mode (in the background)

The first time you run this command, it may take several minutes as Docker needs to download base images and build your application containers.

Accessing the Application

After the containers have started successfully, you can access the application at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080

Checking Service Status

To verify that all services are running correctly, you can check the logs:

docker compose logs -f backend

This will show you the backend service logs. You can replace backend with frontend to check whether the frontend is running correctly.

Stopping the Application

When you're done working with the application, you can stop all services with:

docker compose down

If you also want to remove the volumes (which will delete any data stored in Redis), you can use:

docker compose down -v

Default Admin Credentials

If you use our Supabase database credentials when running the application, the admin credentials are:

• Email: admin@ul.ie
• Password: password

If you use your own Supabase database with no data when running the application, the system comes with a default admin account that is automatically created when the backend starts:

• Email: admin@ul.ie
• Password: admin123

You can use these credentials to log in as an administrator after the application has started.

Troubleshooting

If you encounter connection issues or the backend isn't responding:

1. Check that all containers are running: docker compose ps
2. Review the backend logs for errors: docker compose logs backend
3. Ensure your .env file contains all required variables with correct values
4. Verify that Docker has enough resources allocated (memory and CPU)

If you need to rebuild the containers:

docker compose up --build -d

---

Project Base

This repo contains initial decent defaults for any new Skynet/Compsoc/Any) project.

Tools

Kanban

A basic Kanban can be found by going to the Projects tab.

CI/CD

A CI/CD runner is provided and can be found in the Actions tab.
This runner is Github actions compatible.

Components

Each file has a particular reason for existing, often learnt through (painful) experiences.

Not every file is required (such as .mailmap), but most are strongly recommended.

README.md

Every project should have a README/README.txt/README.md.
This allows ye to concisely state what the repo is about as well as any quickstart guide.
It is often done using Markdown (.md) since that allows for structured text and HTML compatability.

If the documentation gets too long it is advised to create a doc folder as outlined below.

LICENSE

The included LICENSE is the MIT one.
You can dual (multi) license by including LICENSE-MIT and LICENSE-APACHE as what is common in rust projects.

If a project does not have a license then it is source available, rights reserved.

.gitignore

This controls what git is permitted to commit and control.
The file helps ensure that you dont commit code artifacts such as compiled binaries.

It is also a solid defence against committing secrets.

.gitattributes

The .gitattributes file preforms two useful roles in this repo:

1. Ensures a consistent line ending across Windows/Mac/Linux systems.
   • Line endings is useful in a multi device environment.
2. Tells git which files to delegate to LFS.
   • Git is good with text based files.
   • Git-LFS is an addon which stores the files separately and commits a reference to them.
   • This helps ensure teh git repo is not bloated by binary (non text) files.

Git LFS installer: https://git-lfs.com/

.forgejo/workflows/check_lfs.yaml

This is a pipeline config which runs whenever a commit is pushed (push), a merge request is updated (pull_request) or manually requested (workflow_dispatch).

Its purpose is to verify that all files which should be in LFS are in LFS.

When more pipelines are added to a repo then it should be integrated into them.

Github compatability

The pipeline is compatible with Github, to do so you need to rename .forgejo to .github.

Directories

src

It is generally recommended that source code for the project goes into this folder.
This is an industry psudo-standard.

doc

In repo documentation should be put in a doc/docs/documentation folder.
Like src this is an industry psudo-standard.

If the documentation is in the src files this is less important.

Useful but less important

.mailmap

Git works based off of email signatures and a single person may have multiple emails associated with git.
This file maps multiple emails to a single person, or corrects errros in names.

Documentation: https://git-scm.com/docs/gitmailmap

.gitkeep

Git tracks files, to it a folder is just a path to a file.
Thus if a folder is empty then it is invisible to git.
If you wish to commit a folder (as with src and doc in this repo) then you need a placeholder file.
Once there are other files in the repo then the .gitkeep can be removed.

Updating

If any of the files in this repo are updated down the line, such as .gitignore/.gitattributes/.forgejo/workflows/check_lfs.yaml then it is recommended to backport the changes here.