Installation

1. Install prerequisites

   Before you begin, ensure you have the following tools installed on your system:

   • Git (latest version) - Download here
   • Docker Desktop or Docker CLI - Download here
   • Node.js (v24.0 or higher) - Download here
   • pnpm (v11.0 or higher) - Installation guide
   • Redis (v8.0 or higher) - Download here

   Good tools for managing databases

   • MySQL Workbench
   • DBeaver
   • TablePlus
   • HeidiSQL
   • MySQL Command Line etc.
   
   
   

2. Clone the repository

   Choose one of the following methods to clone the project:

   # Using HTTPS
   git clone https://github.com/OAMK-tietotekniikka/ProjectsMS.git

   
   
   

   # Using SSH (if you have SSH keys configured)
   git clone git@github.com:OAMK-tietotekniikka/ProjectsMS.git

   
   
   

   # Using GitHub CLI
   gh repo clone OAMK-tietotekniikka/ProjectsMS

   
   
   

   Navigate to the project directory:

   cd projectMS

   
   
   

3. Install dependencies

   The project has a multi-package structure. You’ll need to install dependencies first:

   • DirectoryprojectMS (install dependencies here)

     • Directorydbinit

       • init.sql
     • Directoryserver (backend)

       • files
       • package.json
     • Directoryfrontend (frontend)

       • files
       • package.json
     • package.json
     • .gitignore

   Install dependencies:

   Root directory (development tools):

   # Don't forget to install pnpm first
   # From the project-ms root directory
   pnpm install

   
   
   

4. Configure environment variables (optional)

   The project includes environment files for both frontend and server components. Review and modify these files as needed for your development environment.

   • DirectoryprojectMS

     • .env

   About environment variables

   Frontend settings

   • VITE_NODE_ENV: Indicates whether the frontend is running in development or production mode.
   • VITE_API_URL: The base URL the frontend uses to communicate with the backend API.

   Database settings

   • DB_HOST: Hostname or IP address of the database server (for example, localhost).
   • DB_USER: Username used to connect to the database.
   • DB_PASSWORD: Password used to connect to the database.
   • DB_NAME: Name of the database.
   • DB_PORT_LOCAL: Port number the database is listening on (for local).
   • DB_PORT_DOCKER: Port number the database is listening on (for docker).
   • DB_CONNECTION_LIMIT: Maximum number of allowed connections to the database.

   Redis settings

   • REDIS_HOST: Hostname or IP address of the Redis server.
   • REDIS_PORT: Port number the Redis server is listening on (default is 6379).

   Server settings

   • SERVER_PORT: Port number the backend server listens on.
   • API_URL: Base URL of the backend API (for example, http://localhost:8000).
   • NODE_ENV: Indicates whether the backend is running in development, test, or production mode.
   • SERVICE_TAGS: Tags that identify the environment (for example, dev, prod, staging).
   • SERVICE_NAME: The name of the backend service (for example, project_ms).
   • IS_DOCKER: Indicates whether the app is running in Docker.
   
   
   

5. Run the project

   Note

   We strongly recommend using the Docker approach for consistency and easier setup. Use the non-Docker method only if you have specific requirements.

   Docker (Recommended)

   Option 1: Fully containerized (Simplest)

   Run the entire application stack using Docker Compose:

   .env

   IS_DOCKER=true

   # Development mode with hot reload
   # Run from the project-ms root directory
   docker-compose -f docker-compose-dev.yml up --build
   
   # Production mode (no hot reload)
   # Run from the project-ms root directory
   docker-compose up --build

   
   

   Tip

   Linux/macOS users: Use the provided Makefile for even easier setup:

   make

   This command shows all available options and can start the containers with fewer commands.

   
   
   

   Option 2: Hybrid approach (More flexible)

   Run the database in Docker while running the server and frontend locally:

   Update the configuration:

   .env

   IS_DOCKER=false

   
   
   

   Start the database:

   Linux/macOS

   cd scripts
   chmod +x ./start_mdb.sh
   ./start_mdb.sh

   Windows (command prompt)

   set INIT_SQL=%cd%\dbinit\init.sql
   
   docker run -d --name mysql-local -p 3307:3306 ^
   -e MYSQL_ROOT_PASSWORD=pwd@123 ^
   -e MYSQL_DATABASE=studentsdb ^
   -e MYSQL_USER=admin ^
   -e MYSQL_PASSWORD=pwd@123 ^
   -v "%INIT_SQL%:/docker-entrypoint-initdb.d/init.sql" ^
   mysql:lts

   
   
   

   Start the server:

   cd server
   pnpm run start:dev

   Default port: http://localhost:8000

   
   
   

   Start the frontend:

   cd frontend
   pnpm run dev

   Default port: http://localhost:3000

   Without Docker (Advanced)

   Caution

   This method requires manual database and Redis setup. Only use if you’re comfortable with database administration.

   Install MariaDB:

   Linux/macOS

   # Linux
   sudo apt update
   sudo apt install mariadb-server
   
   # macOS
   brew install mariadb

   Windows

   Download from mariadb.org/download and follow the installation wizard.

   Configure the database:

   Start MariaDB:

   # Linux/macOS
   sudo systemctl start mariadb
   
   # Windows
   net start MariaDB

   Set up the database:

   # Login to MariaDB
   mysql -u root -p
   
   # Create database and user
   CREATE DATABASE IF NOT EXISTS project_ms;
   CREATE USER IF NOT EXISTS 'admin'@'localhost' IDENTIFIED BY 'pwd@123';
   GRANT ALL PRIVILEGES ON project_ms.* TO 'admin'@'localhost';
   FLUSH PRIVILEGES;
   EXIT;
   
   # Initialize the database schema
   mysql -u root -p project_ms < dbinit/init.sql

   Important

   If your database configuration differs from the default values above, update the .env file accordingly or the application will fail to connect.

   ---

   Install and start Redis:

   Linux/macOS:

   sudo systemctl start redis

   Windows (using WSL):

   sudo apt install redis-server
   sudo service redis-server start

   
   
   

   Update the configuration:

   .env

   IS_DOCKER=false

   
   
   

   Start the application:

   Start the server:

   cd server
   pnpm run start:dev

   Start the frontend:

   cd frontend
   pnpm run dev

Next steps

Once the application is running:

1. Frontend: Navigate to http://localhost:3000
2. Backend API: Available at http://localhost:8000
3. Database: Accessible on port 3307

Both frontend and server support hot reload during development (docker-compose.dev or without Docker), so your changes update automatically.