Skip to content

LRS SQL Setup

Jump to bottom
David edited this page Jun 2, 2025 · 1 revision

LRS SQL is an open-source xAPI Learning Record Store from Yet Analytics that provides a simple, lightweight solution for storing and managing learning records. This guide will walk you through the complete setup process, from downloading LRS SQL to testing your integration with LearnMCP-xAPI.

What is LRS SQL?

LRSQL is a SQL-based Learning Record Store that supports multiple SQL database management systems (DBMSs) like SQLite and Postgres. It's perfect for development and testing because:

  • Zero Configuration Database: Uses SQLite by default - no database setup required
  • Web-Based Interface: Built-in admin dashboard for managing statements and credentials
  • xAPI 1.0.3 Compliant: Conformant with the ADL LRS Test Suite
  • Cross-Platform: Runs on Windows, Linux, and macOS
  • Open Source: Released under the Apache 2.0 license

Downloading and Starting LRS SQL

Step 1: Download LRS SQL

  1. Visit the GitHub Releases page: Go to https://github.com/yetanalytics/lrsql/releases

  2. Download the latest release: Download lrsql.zip from the latest release

  3. Extract the package: Unzip the package to a directory of your choice (e.g., C:\lrsql on Windows or ~/lrsql on macOS/Linux)

Step 2: Configure Admin Credentials

Before starting LRS SQL, you need to set up admin credentials:

  1. Navigate to the config directory in the extracted LRS SQL folder

  2. Rename lrsql.json.example to lrsql.json

  3. Edit the config/lrsql.json file using any text editor and remove the object database

  4. Set your admin credentials by updating these fields:

      "adminUserDefault": "your-admin-username",
  "adminPassDefault": "your-admin-password"

Step 3: Start LRS SQL

  1. Open a terminal/command prompt in the extracted LRS SQL directory

  2. Run LRS SQL with SQLite (simplest option):

    # On Windows
.\bin\run_sqlite.bat

# On macOS/Linux
./bin/run_sqlite.sh

  3. Wait for startup: You should see output indicating that LRS SQL is starting up. Look for a message like:

    Starting new webserver at host 0.0.0.0, HTTP port 8080, and SSL port 8443

  4. Verify it's running: Open your web browser and navigate to http://localhost:8080. You should see the LRS SQL admin interface.

Creating API Credentials

Once LRS SQL is running, you need to create API credentials for LearnMCP-xAPI to authenticate with the LRS.

Step 1: Access the Admin Interface

  1. Open your browser and go to http://localhost:8080
  2. Login with credentials adminUserDefault and adminPassDefault

Step 2: Create New Credentials (API Keys)

  1. Navigate to Credentials: Look for a "Credentials management" section in the admin interface
  2. Click "Add New Credentials"
  3. Configure the credential (Optional):
    • Label: Give it a descriptive name like "LearnMCP-xAPI"
    • Permissions: Ensure it has read and write permissions for statements

Step 3: Record Your API Key and Secret

After creating the credential, you'll see:

  • API Key: A string like abc123def456 (this is your LRSQL_KEY)
  • API Key Secret: A longer string like xyz789uvw012 (this is your LRSQL_SECRET)

⚠️ Important: Copy both values immediately and store them securely.

Configuring LearnMCP-xAPI to Connect

Now that LRS SQL is running and you have API credentials, configure LearnMCP-xAPI to connect using the LRS SQL plugin.

Step 1: Update Your Environment Configuration

Create or edit your .env file in the LearnMCP-xAPI directory:

# Plugin Selection
LRS_PLUGIN=lrsql

# LRS SQL Configuration
LRSQL_ENDPOINT=http://localhost:8080
LRSQL_KEY=your-api-key-here
LRSQL_SECRET=your-api-secret-here

# Actor Configuration (unique per student)
ACTOR_UUID=student-alice-12345

# Optional Configuration
ENV=development
LOG_LEVEL=INFO

Replace the placeholders:

  • your-api-key-here: Use the API Key from Step 3
  • your-api-secret-here: Use the API Secret from Step 3
  • student-alice-12345: Use a unique identifier for each student

Step 2: Test the Connection

Start LearnMCP-xAPI to verify the connection:

python -m learnmcp_xapi.main

If configured correctly, you should see log messages indicating successful connection to the LRS SQL instance.

Troubleshooting

Common Issues

Connection Refused Error

  • Verify LRS SQL is running on port 8080
  • Check that no firewall is blocking the connection
  • Ensure you're using http://localhost:8080 (not https)

Authentication Failed Error

  • Double-check your API key and secret
  • Verify the credentials have proper read/write permissions
  • Ensure you're using the API credentials, not the admin login credentials

Database Errors

  • Make sure the SQLite database file is writable
  • Check available disk space
  • Restart LRS SQL if database corruption is suspected

Viewing Learning Records

Once statements are being recorded, you can view them in the LRS SQL admin interface:

  1. Go to http://localhost:8080
  2. Login with your admin credentials
  3. Navigate to the "Statements" or "xAPI Statements" section
  4. You'll see all recorded learning activities from LearnMCP-xAPI

LRS SQL provides a robust foundation for xAPI-based learning analytics. With this setup complete, you're ready to start capturing and analyzing learning activities through the LearnMCP-xAPI integration!

Clone this wiki locally