Skip to content

UstadMobile/UstadMobile

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ustad Mobile

Ustad Mobile app screenshots

Ustad Mobile enables users to teach, learn, and share: online or offline. It is a learning management system (LMS) built from the ground up to work with or without connectivity. Features include:

  • Online and offline usage of eLearning content with support for Experience API (xAPI), H5P, ePub, PDF, and videos.
  • Assignments where students can submit work to be marked by their teacher or other students (peer marking).
  • Discussion boards
  • Attendance and enrolment tracking
  • Course structuring for course authors to structure content, assignments, discussion boards, text, and (optionally) assign points for completion.
  • Offline sync that works via any Internet connection or via nearby devices (e.g. from teacher device to student device etc). With a class of 30 students this reduces bandwidth consumption 97%+ whilst supporting data sync to the Internet when a connection is available.

Want to collaborate on development? Join us on discord: https://discord.gg/WHe35Sbsg4.

Translations

Ustad Mobile is currently available in English, Dari, Pashto, and Tajik. Translation is done using on our Weblate project. You do not need to be a programmer! Please register on Weblate and then create an issue with the subject "Localization - language name" and let us know what language you would like to translate into. We can then give you permission to start translating!

Translations are stored as Android strings XML resource files in core/src/commonMain/resources/MR. The project uses Moko-Resources to make strings available on all platforms (including JVM and Javascript).

If adding a new language it should be added to the constant in in SupportedLanguagesConfig.kt and app-android/build.gradle resConfigs should be updated. Add the language name to UstadMobileConstants.kt.

Contributing

Contributions are welcome, there are many ways to contribute as a developer, translator, or user. See the CONTRIBUTING.md for details. If you're unsure about anything, please join our discord server or create an issue here on GitHub and label it as a question.

Documentation for users

The documentation here on Github is intended for those who are contributing to the project (inc translation, software development, bug reporting, testing, etc) and technical users (e.g. developers, server admins). If you want documentation for end users, please see the manual on ReadTheDocs at https://ustadmobile.readthedocs.org/

Installing on a server (self-hosting)

See INSTALL.md for instructions for installation on your own server using binary downloads.

Development environment setup:

These instructions are intended for developers who wish to build/run from source code.

This is a Kotlin Multiplatform project. This repository contains the Android app, web app, and backend server source code in its modules. Android Studio is the development environment for the entire project.

  • Step 1: Download and install Android Studio: If you don't already have the latest version, download from https://developer.android.com/studio.

  • Step 2: Make sure that java is on your system path: If you already have OpenJDK17, you can use that, otherwise you need to download from the Java website or install using your system package manager.

Supported JDK Version: JDK17 (only). JDK21 not supported yet due to Proguard issues on app-desktop.

Linux:

Install OpenJDK17, ffmpeg, and mediainfo using the system package manager e.g.

sudo apt-get install openjdk-17-jdk ffmpeg mediainfo

Windows:

Download and install Java (JDK17) if not already installed from the Java site https://www.oracle.com/java/technologies/downloads/#jdk17-windows

The installer should automatically put the java command into the system PATH environment variable.

If you need to do this manually, search for "Environment Variables" in Windows - then "Edit the system environment variables". Create a new environment variable. Set the variable name to JAVA_HOME and set the value to the directory where you have installed Java.

Now find the PATH variable. Append ;%JAVA_HOME%\bin to the value and save it.

Further details: see the Java website.

If you don't have ffmpeg installed, the server can download it for you when you run it for the first time.

  • Step 3: Import the project in Android Studio: Select File, New, Project from Version Control. Enter https://github.com/UstadMobile/UstadMobile.git and wait for the project to import. Switch to the dev-mvvm-primary branch (Menu: Git - Branches - search for dev-mvvm-primary - checkout ).

  • Step 4: Build/run the server: Run the server locally:

Linux/MacOS:

$ ./runserver.sh --siteUrl http://your.ip.address:8087/

Windows:

$ runserver.bat --siteUrl http://your.ip.address:8087/

The siteUrl parameter must match the address that you use to access the system (e.g. in the browser or when entering the link on the Android app).

As above, your.ip.address is your IP address (e.g. 192.168.1.2). If the siteUrl changes and the old site url is inaccessible, then this may make content uploaded before the change inaccessible.

This will start the server on port 8087. The admin password will be randomly generated - you can find it in app-ktor-server/data/singleton/admin.txt .

This will run the REST API which is required by the Android and web apps. It will not include the web client app itself. To use the web client app in the browser, you must build/run it (as below).

  • Step 5: Build/run the Android and/or web client version : see app-android for the Android app, app-react for the web app.

Note: If self-registration is enabled, you must add an email server configuration to the ustad-server.conf file. See app-ktor-server/README.md for details on using the ustad-server.conf file.

Code structure

This multi-module Gradle project built using Kotlin Multiplatform. It builds for:

  • Android (app-android)
  • KTOR Server (JVM) (app-ktor-server)

Additional information on coding structure is available as follows:

  • ARCHITECTURE.md - architecture overview of the tech stack.
  • CODING-STYLE.md - coding style including how MVVM is applied using Kotlin Multiplatform.
  • DBSCHEMA.md - Database schema of the database tables used by the app.

Code is contained (mostly) in the following modules:

  • app-android: Contains the Android app
  • app-desktop: Contains Desktop app based on Compose Multiplatform.
  • app-react: Contains the web app (written in Kotlin, using React via kotlin-wrappers)
  • app-ktor-server: Contains the HTTP rest server (implemented using KTOR)
  • core : Contains view models, ui state, core business logic.
  • sharedse: Contains some shared implementations for operating systems with a disk (JVM/Android)
  • lib-database: contains the database: DAOs (e.g. SQL queries), and entity classes.
  • lib-ui-compose: contains Compose multiplatform UI code used by app-android and app-desktop
  • lib-util: Small utility functions
  • test-end-to-end End-to-end tests that run the app and server.
  • testserver-controller An HTTP server that can control starting and stopping the main server, and manage adb screen recording. Used by end-to-end testing.

To build / run versions for any given platform please see the README in the module for that platform.

Legal and license

Copyright 2015-2023 UstadMobile FZ-LLC. Documentation: CC-BY license. Code and all other works: AGPLv3 license.