Runestone Academy has been there for a while (since 2011). To be able to contribute to Runestone Academy as an open-source contributor, one must understand the architecture behind Runestone, especially since everything that has ever existed in Runestone now gets combined into one mono repository called: Runestone MonoRepo. This repository combines various projects under the Runestone umbrella into a single structure using a polylith and, more recently, a mono repo architecture.
Another thing to keep in mind is the structure of Runestone servers, a crucial component of Runestone, serving as the backbone for delivering content and materials to users. You can either run an existing server or build a server on your own, depending on the purpose.
Now, let’s dive into the main components of the Runestone mono repo and necessary servers!
Polylith
In the Runestone project, the code is organized using the Polylith software architecture, a structure that simplifies the management of interconnected projects by grouping them into distinct folders.
The top-level folders include “projects” for deployable artifacts like servers and command-line tools, “bases” serving as the public-facing API for a project, “components” containing code that supports multiple projects or bases, “development” for experimental and early work, “docs” housing the source code for documentation, and “tests” containing automated tests for various projects. Each folder corresponds to a specific concept in the Polylith architecture. The “projects” folder, for example, holds deployable artifacts such as servers, each organized into its respective subfolder.
This organization allows for efficient code sharing among different projects, streamlining development and promoting a modular and scalable approach.
Poetry
In the Runestone project, Poetry serves as the tool for managing Python dependencies, ensuring an effective development process.
To align with the Polylith structure, specific plugins are integrated into Poetry globally. These plugins, namely poetry-polylith-plugin, poetry-multiproject-plugin, and poetry-dotenv-plugin, enhance the code organization and compatibility with the Polylith architecture.
The integration of Poetry into the Polylith structure supports the management of projects, components, bases, and development efforts, facilitating efficient collaboration and code reuse.
Inside Poetry, there are different projects running:
- w2p_login_assign_grader
- book_server
- author_server
- dash_server
- rsmanage
- jobe
- nginx
- redis
Each project has its distinct purpose within the Runestone system, contributing to functions like web serving, authoring, user management, job running, and caching.
Postgresql
The Postgresql database is a crucial part of Runestone, linking different aspects of the system. It serves as the storage and retrieval system for critical data, facilitating seamless communication and interaction between different elements of the Runestone platform. The database is where user accounts, course information, and interactive content are stored, enabling the Runestone server to deliver personalized and dynamic learning experiences.
By setting up and configuring Postgresql appropriately, the Runestone server can leverage this database to manage user authentication, store progress data, and provide a reliable foundation for the interactive features and content customization that define the Runestone learning experience.
Runestone Server
The Runestone server’s structure relies heavily on the use of environment variables, which are crucial for managing sensitive information and providing flexibility during startup. These variables play a dual role, with some being essential on the host side (h), some on the docker side (d), and others significant for both (b).
To set up these variables, a .env file is required, residing in the root level of the repository. This file is read by docker-compose and used to configure environment variables within the docker containers. Users can customize values, especially for variables like BOOK_PATH, DEV_DBURL, and DC_DEV_DBURL, depending on their specific setup preferences.
These core variables determine paths, database connections, and other critical settings. The Runestone server’s reliance on environment variables showcases its adaptability and security measures, ensuring that sensitive information is kept confidential while providing a means for users to tailor the system to their needs.
Book Server
To run a course on Runestone, you must build/add a book. The book server in your local environment is running independently from the Runestone server. There are two packages you must install before building the book: npm (Node Package Manager) installed and fulfilling the JavaScript dependencies outlined in the package.json file found in bases/rsptx/interactives.
By adding a book to the local host, developers and content creators can thoroughly test the book’s content, interactive components, and other features within the Runestone environment. This ensures that the book functions as expected and provides an accurate representation of the educational material.
Bases and Components
Bases in Runestone play a pivotal role by defining the API for user interactions with the server, encompassing routes to web pages and API endpoints. These serve as the foundational structure that facilitates communication between users and the Runestone environment.
The book_server_api package is a key component, outlining crucial subpackages and modules. Additionally, the rsmanage package provides essential commands for managing various aspects of the Runestone server, ranging from adding courses and users to handling database operations. Components and shared pieces of code, such as those found in the cl_utils package, contribute to the functionality of multiple bases.
Finally, I am working on is how to render the clock image properly. The issue is within the webpack-based approach in Runestone Components. To resolve this issue, it is noted to relocate the image and modifying the corresponding CSS references, likely within the runestone/common/css directory. Similarly, addressing the play overlay icon, located in runestone/common/js/bookfuncs.js, may involve transitioning it to CSS for more versatile rendering and compatibility, particularly with the pretext.