---

Getting Started with your Runestone Development Environment

Set up a virtualenv for Runestone work

There are a number of dependencies, and this will make it easy to complete the installations for Runestone development.

Install the development version of Runestone Components

The RunestoneComponents GitHub repository's readme has a bunch of information about how to do this. This is the first part you should install. You can stop here and look at that README if you don't want to do any development on the server.

Runestone Components itself is in PyPi as runestone, so you can install it with pip, but if you're working on code development of anything for Runestone Interactive, you'll likely want to be able to interact with the code and see the development versions. Activate your virtual environment, and fork and clone this repository.

Install Runestone Components and its requirements

With your virtual environment activated, access the root of your Runestone Components directory, and run pip install -e {path to your clone of RunestoneComponents}

Then, with your virtualenv still activated, navigate to the root of your RunestoneComponents directory and run pip install -r requirements.txt to install all Runestone Components dependencies.

Install the web2py application for the Runestone Server

The Runestone Server is a web2py application, so you first need to download web2py. You should download the .zip file of source code from here (if you get web2py from apt-get or GitHub, you may miss some of the necessary submodules).

Next, follow the instructions for the Runestone Server, starting with navigating to applications inside the web2py directory, and forking and cloning the Runestone Server repository there, with the name runestone.

The Runestone Server README provides instructions for how to do that (but be careful that you clone your fork, so you can make pull requests. If you copy directly from the README, you'll clone the RunestoneInteractive version, not yours).

You'll also need to have installed all of the server's Python dependencies in your virtual environment, so, navigate to the root of your new runestone repository, which should be at web2py/applications/runestone with your virtualenv activated, and run pip install -r requirements.txt.

The Runestone Server README also includes instructions for how your installation process should vary depending upon your operating system (Windows, Linux, Mac).

Install and set up your database

You'll need to install the Postgresql database server. Instructions for doing so are included in the server README as well if you have not already done so. You can find instructions about how to do so on the Runestone Server README. (If you use a Mac, we recommend using Homebrew to brew install postgresql rather than using the Postgres app.)

Follow the instructions in the Runestone Server README to create and set up your database. If you can't run localhost:8000/runestone yet, no fear -- go on to the next step!

Choose and build a book

The Runestone Server, combined with the Runestone Components, power the interactive textbooks that Runestone Interactive is made for. Choose a book to start with (e.g. the thinkcspy book, or any other you find the repositories for from the library, and fork and clone that book repository inside the web2py/applications/runestone/books directory.

Then, navigate to the root of that book directory, with your virtualenv still activated, and run pip install -r requirements.txt a last time. This will install all last requirements for building the book so you can see it rendered and deploy it properly.

Finally, in the command prompt, export your environment variables, so that your database access will work when you build a textbook -- this saves e.g. question data to the database, etc. Type the following at the command prompt to do so:

        export DBNAME=runestone
        export DBPASS=yourpassword
        export DBHOST=localhost
        export DBUSER=yourusername ((NOTE: could be "postgres", depending on how you've done your db setup))

Then, run runestone build. To see the book properly built when you run the web2py server, after you run the runestone build command, you'll need to run runestone deploy.

Finish setting up your database as needed

Follow the instructions in the Runestone Server README to complete your database setup. (If you run into any problem with "The Easier Way", The Harder Way" the README explains is not too hard! Just make sure you follow the instructions carefully.)

Important note: If at any point in the process you had database trouble and dropped a database to start over, make sure you've also removed everything in the databases folder! Otherwise, Runestone won't know that it needs to create the tables again...

Get started!

You're all set! Check out the issues on the Components repository and on the Server repository. If you want to get started building the components test suite, check out the instructions in the Runestone Components README. You can also join the mailing list!

---

More Information

• We have a full set of developer docs here
• For a quick reference when authoring content, writing tests, or otherwise working with the Runestone Components, type runestone help list or runestone help directivename For example:

      $ runestone help codelens
  
      .. codelens:: uniqueid
         :tracedata: Autogenerated or provided
         :caption: caption below
         :showoutput: show stdout from program
         :question: Text of question to ask on breakline
         :correct: correct answer to the question
         :feedback: feedback for incorrect answers
         :breakline: Line to stop on and pop up a question dialog
         :python: either py2 or py3
  
          x = 0
          for i in range(10):
             x = x + i
         

• Check out this Demo Site to see a bunch of the available components in action.

---