Building from Source

Quick Start

This is the “Mini Quick Start” - for complete configuration steps, see the Sakai Quick Start Guide.

Basic Build

Build Sakai using Maven:

mvn install

The first build will take 15-30 minutes as Maven downloads dependencies.

Build and Deploy

Deploy Sakai to your Tomcat installation:

mvn clean install sakai:deploy -Dmaven.tomcat.home=/path/to/your/tomcat

Replace /path/to/your/tomcat with your actual Tomcat directory path.

Build Profiles

Sakai uses Maven profiles to control what gets built:

All Profile (Default)

Builds all standard modules:

mvn clean install -P all

This profile includes:

Core kernel and APIs
All standard tools (Assignments, Gradebook, Forums, etc.)
Web components
Portal and login
Admin tools

API Only Profile

Build only API modules for faster compilation:

mvn clean install -P api

Experimental Profile

Includes experimental and contrib tools:

mvn clean install -P experimental

Pack Profiles

Create release artifacts:

mvn clean install -P pack-bin

Build Commands

Full Clean Build

Perform a complete clean build:

mvn clean install

Skip Tests

Build faster by skipping tests:

mvn clean install -DskipTests

Only skip tests during development. Always run tests before creating a pull request.

Build Specific Module

Build only a specific tool or module:

# Navigate to module directory
cd assignment
mvn clean install

Offline Build

Build without checking for updates:

mvn clean install -o

Skip Checkstyle

Bypass Checkstyle validation (emergencies only):

mvn clean install -Dcheckstyle.skip=true

Do not commit code that requires -Dcheckstyle.skip=true. Fix the violations instead.

Deploy to Tomcat

Standard Deployment

Deploy built artifacts to Tomcat:

mvn clean install sakai:deploy -Dmaven.tomcat.home=/path/to/tomcat

Quick Redeploy

After making changes to a single tool, redeploy just that module:

Build the module

cd assignment
mvn clean install

Deploy the module

mvn sakai:deploy -Dmaven.tomcat.home=/path/to/tomcat

Restart Tomcat

cd /path/to/tomcat/bin
./shutdown.sh
./startup.sh

Frontend Build Commands

For web components development:

Lint JavaScript

Check code quality:

cd webcomponents/tool/src/main/frontend
npm run lint

Auto-fix linting issues:

npm run lintfix

Bundle JavaScript

Create production bundles using ESBuild:

npm run bundle

Analyze Bundles

Generate bundle analysis:

npm run analyze-bundle

Type Checking

Run Lit analyzer for static type checking:

npm run analyze

Run Tests

Execute Web Test Runner tests:

npm run test

Running Sakai

Start Tomcat

After deployment, start Tomcat:

cd /path/to/tomcat/bin
./startup.sh && tail -f ../logs/catalina.out

Sakai typically takes 30-60 seconds to start up.

Access Sakai

Once started, open your browser to:

http://localhost:8080/portal

Default credentials (if using demo data):

Username: admin
Password: admin

Stop Tomcat

cd /path/to/tomcat/bin
./shutdown.sh

Testing Builds

Run Unit Tests

Execute tests for a single module:

mvn test -Dtest=TestClassName

Run E2E Tests

Run Playwright end-to-end tests:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PLAYWRIGHT_BASE_URL=https://localhost:8080
mvn -f e2e-tests/pom.xml test

Run a specific test:

mvn -f e2e-tests/pom.xml -Dtest=AssignmentTest test

Build Optimization

Parallel Builds

Speed up builds using multiple threads:

mvn clean install -T 4

This uses 4 threads. Adjust based on your CPU cores.

Maven Daemon

Use Maven Daemon for faster repeated builds:

# Install mvnd
brew install mvnd  # macOS

# Use mvnd instead of mvn
mvnd clean install

Troubleshooting

Out of Memory

Increase Maven memory:

export MAVEN_OPTS="-Xmx2048m -XX:MaxMetaspaceSize=512m"
mvn clean install

Dependency Issues

Clear Maven cache and rebuild:

rm -rf ~/.m2/repository/org/sakaiproject
mvn clean install

Port Conflicts

Change Tomcat port in server.xml:

<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443" />

Change 8080 to another port like 9090.

Next Steps

Tool Development

Learn to develop Sakai tools and modules

Testing Guide

Write and run tests for your code

Getting Started

Core Concepts

Key Features

Administration

Development

​Quick Start

​Basic Build

​Build and Deploy

​Build Profiles

​All Profile (Default)

​API Only Profile

​Experimental Profile

​Pack Profiles

​Build Commands

​Full Clean Build

​Skip Tests

​Build Specific Module

​Offline Build

​Skip Checkstyle

​Deploy to Tomcat

​Standard Deployment

​Quick Redeploy

​Frontend Build Commands

​Lint JavaScript

​Bundle JavaScript

​Analyze Bundles

​Type Checking

​Run Tests

​Running Sakai

​Start Tomcat

​Access Sakai

​Stop Tomcat

​Testing Builds

​Run Unit Tests

​Run E2E Tests

​Build Optimization

​Parallel Builds

​Maven Daemon

​Troubleshooting

​Out of Memory

​Dependency Issues

​Port Conflicts

​Next Steps

Tool Development

Testing Guide

Build docs developers (and LLMs) love

Quick Start

Basic Build

Build and Deploy

Build Profiles

All Profile (Default)

API Only Profile

Experimental Profile

Pack Profiles

Build Commands

Full Clean Build

Skip Tests

Build Specific Module

Offline Build

Skip Checkstyle

Deploy to Tomcat

Standard Deployment

Quick Redeploy

Frontend Build Commands

Lint JavaScript

Bundle JavaScript

Analyze Bundles

Type Checking

Run Tests

Running Sakai

Start Tomcat

Access Sakai

Stop Tomcat

Testing Builds

Run Unit Tests

Run E2E Tests

Build Optimization

Parallel Builds

Maven Daemon

Troubleshooting

Out of Memory

Dependency Issues

Port Conflicts

Next Steps