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.
3. Use the admin search feature at /web/admin/search to find the account request, expand the row, and retrieve the account registration link to activate the instructor.
4. From the instructor home page at /web/instructor/home, enroll a test student.
5. Use the admin search feature to find the student, expand the row, and retrieve the course join link to activate the student account.
6. 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.