Runestone Academy is an open-source project and our mission is to equip the nation's STEM teachers with open-source content, tools and strategies they need to create engaging, accessible, and effective learning experiences for their students. You might do this through our website, https://runestone.academy or by running your own server. Or you may be an author or budding author that has a great idea for a book. Or you may be a technology coordinator that wants to run a private server. Or you may be a researcher at a large university that is looking for a platform to test your ideas. We are here for you. This repository is the home of the Runestone Academy software. We would welcome your help. And we are happy to help you get started.
If you want to use the Runestone Academy servers to run a class using an existing book or if you want to author a book, you likely do not need to run your own copy of Runestone:
- I want to run a class based on an existing book - Instructor guide
- I want to author a book. This is now done using PreTeXt. PreTeXt is an authoring language that is designed to produce books that can be served on Runestone. PreTeXt Author Guide
- I want to customize a book for my class - Customizing a Textbook
If you want to do development on Runestone, or run your own server, you will need to set up your own copy of the Runestone software:
- I want to contribute to the Runestone Academy software - Finish reading this page, then move on to the Contributing Guide
- Running a server for my own class? See Running a Server
- Running a server for my school or larger group? See Running a Server
Chat with us on Discord
This repository collects together the various repositories related to the Runestone Academy software. The idea of combining several repositories into a single structure was motivated and inspired by the Python polylith tools and projects.
As Runestone grew over the years we accreted loads of new functionality without ever stopping to reconsider an architecture that would support easier implementation of new features while providing stability for fundamental parts of the project that need to scale. (Docker was not invented at the time Runestone development started!)
This repository uses a polylith structure in order to allow the several projects under the Runestone umbrella to share code, provide common ways of accomplishing similar tasks, and hopefully make it easier for a newcomer to contribute to the project. If you don't know what a polylith is don't let that deter you. It is just a fancy way of saying that we have a bunch of projects that share a lot of code.
Finally, in 2023 we decided to move to a mono repo. The goal of this re-working of the Runestone code was to provide a very docker-friendly set of servers and services using a polylith software architecture. The following diagram shows what we are aiming at.
Each of the servers in the diagram above has or will become a project in this repo. Each individual server is described by a docker file and can be run either as a docker container or on a physical server set up for the purpose. A collection of docker compose profiles are used to control which servers are started for which purposes.
basic- this will start up the default servers plus a database server in the composed app.dev- this will start up the default servers plus development nginx server in the composed app.production- this will start up the default servers plus thepgbouncerserver in the composed app.author- this will start up the default servers plus theauthorserver in the composed app.
See Our Read the Docs page for more complete documentation. After reading the whole page, please continue to the Contributing Guide.
There is so much to do on this project, and we are happy to accept contributions. Please see the Contributing Guide for more information. We are especially interested in contributions that help us to improve the documentation, and the test coverage of the code.
If you want to know where we are going, and what things are in active development or in need of immediate help please take a look at our projects page on github: Runestone Projects
Longer term development goals are described in the Runestone Roadmap.
Note that the move to a mono repo means that the history of the individual repositories was lost. I am sorry for this, but I think the benefits of a mono repo will be worth it. The original repositories are still available, but they are no longer being actively developed. If you need to point to your contributions to Runestone, please use the old repos as a reference.
The Runestone community has been actively developing and supporting this project since 2011.
Join us on Discord
The new book authoring language is PreTeXt. We have a very active community of PreTeXt authors and developers. If you are interested in contributing to the PreTeXt project, please visit the PreTeXt project page.
POSE Training Program - Spring 2023 Pilot
Awarded: May 18, 2023
