Getting started

This guide will help you set up a local development environment for TEAMMATES.

Prerequisites

Before you begin, a basic familiarity with the following will help:

• Git
• Java
• Angular/TypeScript

Step 1: Fork and Clone the Repository

1. Install Git.
2. Fork the project repository at github.com/TEAMMATES/teammates and clone your fork locally.
3. Add the main repository as a remote and fetch it:

git remote add upstream https://github.com/TEAMMATES/teammates.git
git fetch upstream

    

    Copy
    

    


    
    
    

Verification: Run git branch -r and verify upstream/master is listed.

4. Track the main repo's master branch:

git checkout master
git branch -u upstream/master

    

    Copy
    

    


    
    
    

Step 2: Install Tools

1. Install Java JDK 21.
   • JDK 25 is also supported, as long as newer language features are not used.
2. Install Node.js (minimum version 24).
3. Install Docker.

Step 3: Configure the Project

1. Generate the main config files:

./gradlew createConfigs

    

    Copy
    

    


    
    
    

gradlew.bat createConfigs

    

    Copy
    

    


    
    
    

Verification: A gradle.properties file should appear in the project root.

1. Edit gradle.properties if needed:

   • Set org.gradle.java.home if you want to use a specific JDK.

2. Install frontend dependencies:

npm ci

    

    Copy
    

    


    
    
    

Verification: A node_modules folder should appear in the project root.

3. Generate frontend type definitions

./gradlew generateTypes

    

    Copy
    

    


    
    
    

gradlew.bat generateTypes

    

    Copy
    

    


    
    
    

Step 4: Run the Application

1. Start the database:

docker compose up -d

    

    Copy
    

    


    
    
    

2. Start the backend server:

./gradlew serverRun

    

    Copy
    

    


    
    
    

gradlew.bat serverRun

    

    Copy
    

    


    
    
    

The backend will be available at http://localhost:8080.

3. Start the frontend server:

npm run start

    

    Copy
    

    


    
    
    

The frontend will be available at http://localhost:4200.

Step 5: Set up test accounts

To test TEAMMATES locally, you will need an instructor and a student account.

1. Visit /web/admin/home and log in as admin (app_admin@gmail.com).
2. Add an instructor account and use the generated join link to activate it.
3. From the instructor home page at /web/instructor/home, enroll a test student.
4. Use the admin search feature at /web/admin/search to find the student, expand the row, and retrieve the course join link to activate the student account.
5. You now have access to all TEAMMATES features.

Step 6: Next Steps

Your environment is now ready. Here's what to do next:

1. Read the Contributing Guidelines and Development Workflow.
2. Browse good first issues to find something to work on.