Running a Runestone ServerΒΆ

Maybe you just want to run your own server for a small course. Maybe you are an author who just wants to preview what your book will look like in Runestone. (Hint: Its going to look very much like the plain html, unless you have Java, C or C++ code) Or maybe you are interested in getting involved in the development of the Runestone tools, but want to experiement first. This document will help you get started without having to install a lot of software on your own machine, or having to worry about setting up a web server or database or any development environment. This assumes that you are using some kind of linux machine. If you are using a modern apple silicon based mac, then you will need to build the images locally until I figure out how to publish both arm and x86 images to docker hub.

The Runestone server uses docker compose to start up a number of containers that work together to provide the Runestone environment. Here are the steps to get started:

  1. Install Docker and Docker Compose on your machine. You can find instructions for your operating system here: https://docs.docker.com/compose/install/ If you already have docker installed you can skip this step. but make sure that docker compose version tells you that you are running 2.20.2 or later. The current version is 2.27.1

  2. Clone the Runestone repository to your local machine. You can do this by running the following command: git clone https://github.com/RunestoneInteractive/rs.git

  3. Change to the rs directory: cd rs

  4. copy the sample.env file to .env: cp sample.env .env At a minimum you will then need to edit .env to provide a value for BOOK_PATH

  5. Run the command docker compose pull this will pull the prebuilt images for the runestone services from our public docker hub repository. This will take a while the first time you run it, but subsequent runs will be faster.

  6. Start the database server by running the following command: docker compose up -d db

  7. Initialize the database by running the following command: docker compose run --rm rsmanage rsmanage initdb

  8. Start the Runestone server by running the following command: docker compose up -d

  9. You should now be able to access the Runestone server by going to http://localhost in your web browser. You can log in with the username testuser1 and the password xxx.

  10. Now add a book. cd /your/path/to/book (the same value you used for BOOK_PATH) and clone a book. For example: git clone https://github.com/RunestoneInteractive/overview.git

  11. Add the book to the database. (Note this is not needed for overview since we preload many books) docker compose run --rm rsmanage rsmanage addcourse You will then be prompted to enter some information about the course:

    Database connection successful
    Course Name: foo
    Base Course: foo
    Your institution: Runestone
    Require users to log in [Y/n]: n
    Enable pair programming support [y/N]: n
    

    If the course already exists in the database, it will ask you if you want to use a different name.

  12. Now go back to the rs directory and run the following command: docker compose run --rm rsmanage rsmanage build overview Insert your courses name in place of overview. If you are building a PreTeXt book you will need to run docker compose run --rm rsmanage rsmanage build --ptx yourbook

  13. You should now be able to access the overview book on your server running on localhost. The url to go directly to your book is is http://localhost/ns/books/published/yourbook/index.html`

If you want to stop the server, you can run the following command: docker compose stop

Almost all of this could be scripted, and it would be an awesome idea for a PR if someone wanted to create a little script that would do all of this for you. If you are interested in doing that, please let us know and we can help you get started.