Skip to main content
This guide will help you build and run Sakai from source on your local machine. Perfect for developers, administrators evaluating Sakai, or anyone wanting to explore the platform.
For production deployments, see the Installation Guide. This quick start is designed for development and testing environments.

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Java Development Kit 17

Sakai requires Java 17. We recommend Eclipse Temurin (formerly AdoptOpenJDK).
# Verify Java version
java -version
Should output Java 17 or higher.
2

Apache Maven 3.6+

Maven is required to build Sakai from source.
# Verify Maven version
mvn -version
3

Apache Tomcat 9

Download Tomcat 9 from tomcat.apache.orgExtract to a directory like /opt/tomcat9 or C:\tomcat9
4

MySQL or MariaDB

Sakai requires a database. MariaDB is recommended.
# Install MariaDB on Ubuntu/Debian
sudo apt-get install mariadb-server

# Install on macOS with Homebrew
brew install mariadb

​
Build Sakai from Source

Clone the Sakai repository and build it:
1

Clone the Repository

git clone https://github.com/sakaiproject/sakai.git
cd sakai
Source: README.md:51-53
2

Build with Maven

mvn clean install
This will take 10-20 minutes on first build. Maven will download dependencies and compile all modules.Source: README.md:16-19
Use mvn clean install -DskipTests to skip tests and speed up the build.

​
Configure Tomcat

Sakai requires specific Tomcat configuration:
1

Set Environment Variables

Create or edit setenv.sh (Linux/Mac) or setenv.bat (Windows) in Tomcat’s bin/ directory:
# Linux/Mac: bin/setenv.sh
export JAVA_OPTS="-server -Xms2g -Xmx2g -XX:+UseG1GC"
export JAVA_OPTS="$JAVA_OPTS --add-opens=java.base/java.lang=ALL-UNNAMED"
export JAVA_OPTS="$JAVA_OPTS --add-opens=java.base/java.time=ALL-UNNAMED"
export JAVA_OPTS="$JAVA_OPTS --add-opens=java.base/java.util=ALL-UNNAMED"
Source: docker/tomcat/bin/setenv.sh:3-19
2

Create Sakai Directory

mkdir -p /path/to/tomcat/sakai
This directory will hold Sakai configuration and content.

​
Setup Database

Use Docker to run MariaDB quickly:
docker run -p 127.0.0.1:53306:3306 -d \
  --name="sakai-mariadb" \
  -e "MARIADB_ROOT_PASSWORD=sakairoot" \
  -e "MARIADB_DATABASE=sakai" \
  mariadb:10 --lower-case-table-names=1
Source: docker/README.md:93-98

​
Deploy to Tomcat

1

Deploy Sakai

From the Sakai source directory:
mvn clean install sakai:deploy -Dmaven.tomcat.home=/path/to/tomcat
Replace /path/to/tomcat with your Tomcat installation directory.Source: README.md:31-32
2

Start Tomcat

cd /path/to/tomcat/bin
./startup.sh && tail -f ../logs/catalina.out
Wait for the message: Server startup in [xxxxx] millisecondsSource: README.md:34-37
3

Access Sakai

Open your browser to:
http://localhost:8080/portal
Default login credentials:
  • Username: admin
  • Password: admin
Source: README.md:40

​
First Steps in Sakai

After logging in, try these activities:

Create a Site

Navigate to Sites → New Site to create your first course or project site

Add Tools

In your site, click Site Info → Manage Tools to add Assignments, Gradebook, Forums, etc.

Create Content

Use the Resources tool to upload files and organize course materials

Add Users

Go to Sites → Membership to add participants to your site

​
Development Workflow

If you’re developing Sakai tools or features:
1

Build Single Module

After making changes to a specific module:
cd assignment
mvn clean install sakai:deploy -Dmaven.tomcat.home=/path/to/tomcat
2

Restart Tomcat

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

Test Changes

Refresh your browser to see the changes (you may need to clear cache).

​
Frontend Development

For web component development: 
cd webcomponents/tool/src/main/frontend

# Install dependencies
npm install

# Run linter
npm run lint

# Build components
npm run bundle
Source: AGENTS.md:12-15

​
Docker Quick Start

Alternative: Run Sakai with Docker: 
# Build Sakai Docker image from source
cd docker
docker build --build-arg GIT_CACHEBUST=$(date +%s) \
  --build-arg release=master -t sakai \
  -f ./Dockerfile.source .

# Start MariaDB
docker run -p 127.0.0.1:53306:3306 -d --name="sakai-mariadb" \
  -e "MARIADB_ROOT_PASSWORD=sakairoot" \
  mariadb:10 --lower-case-table-names=1

# Run Sakai
docker run --rm -p 8080:8080 --name sakai-tomcat \
  --link sakai-mariadb sakai
Source: docker/README.md:33-39, docker/README.md:93-98, docker/README.md:112

​
Troubleshooting

Increase heap memory in setenv.sh:
export JAVA_OPTS="-server -Xms4g -Xmx4g"
Verify database is running:
mysql -u sakai -p sakai
Check sakai.properties has correct credentials.
Either stop the conflicting service or change Tomcat’s port in server.xml:
<Connector port="8090" protocol="HTTP/1.1" />
Clean Maven cache and rebuild:
mvn clean install -U

​
Next Steps

Architecture Guide

Understand Sakai’s layered architecture and design patterns

Installation Guide

Deploy Sakai for production use

Development Guide

Set up a complete development environment

API Documentation

Explore Sakai’s Java APIs and REST endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us