Building from Source

Build and deploy Sakai LMS from source code

Quick Start

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

Basic Build

Build Sakai using Maven:

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:

Binary Pack

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:

1. Build the module

   cd assignment
   mvn clean install
   
2. Deploy the module

   mvn sakai:deploy -Dmaven.tomcat.home=/path/to/tomcat
   
3. 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:

Test Class

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