You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 experiment 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 will work for both linux and macOS on Apple Silicon or Intel based machines. It will also work on Windows, but you will need to install WSL2 and Docker Desktop for Windows.
5
5
6
-
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:
6
+
Prerequisites
7
+
-------------
7
8
8
-
#. 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.38.2.
9
-
- If you are using Docker Desktop, you will probably need to add paths to to the list of virtual file shares. Go to Settings -> Resources -> File Sharing and add the path to the rs directory you will create below, as well as the ``BOOK_PATH`` directory you will create below.
9
+
Before running the setup script, you need:
10
10
11
-
#. 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``
11
+
**Required:**
12
12
13
-
#. Change to the rs directory: ``cd rs``
13
+
- **Docker Desktop** with Docker Compose 2.20.2 or later (current version: 2.38.2)
14
+
15
+
- Download from https://docs.docker.com/compose/install/
16
+
- Make sure Docker Desktop is running before starting the setup
17
+
- For Windows: Enable WSL2 integration in Docker Desktop settings
18
+
- **Important**: Configure file sharing in Docker Desktop (Settings → Resources → File Sharing) to include the directory where you'll create your Runestone configuration and your ``BOOK_PATH`` directory. Without this, Docker won't be able to access your book files.
14
19
15
-
#. 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``
20
+
- **WSL2** (Windows users only)
21
+
22
+
- The script must run from a WSL2 terminal (Ubuntu, Debian, etc.)
23
+
- Do not use PowerShell or Command Prompt
16
24
17
-
#. 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.
25
+
**Optional:**
18
26
19
-
#. Start the database server by running the following command: ``docker compose up -d db``
27
+
- **Git** - Only needed if you want to clone book repositories
20
28
21
-
#. Initialize the database by running the following command: ``docker compose run --rm rsmanage rsmanage initdb``
29
+
- Most users will want to add books, so this is recommended
30
+
- You can install it later if you skip book setup initially
22
31
23
-
#. Start the Runestone server by running the following command: ``docker compose up -d``
32
+
Quick Start
33
+
-----------
24
34
25
-
#. 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``.
35
+
Get Runestone running with a single command:
26
36
27
-
#. 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``
37
+
.. code-block:: bash
28
38
29
-
#. Add the book to the database. First return to the rs directory. Run ``docker compose run --rm rsmanage rsmanage addbookauthor`` You will then be prompted to enter some information about the book and the author.:
Runestone username of an author or admin: : testuser1
43
+
**Before running the command:**
40
44
41
-
If the course already exists in the database you will get an error message and the command will exit.
45
+
#. Navigate to where you want the configuration files created (e.g., ``mkdir ~/runestone && cd ~/runestone``)
46
+
#. Make sure you have the prerequisites installed (see above)
47
+
#. For Windows users: Run this from a WSL2 terminal, not PowerShell or Command Prompt
42
48
43
-
Note: This command sets up a "base course" This is not a course you would normally teach out of. You would normally create a course to teach from throught the web interface or using the ``addcourse`` sub command.
49
+
**After setup completes:**
44
50
45
-
#. Run the following command: ``docker compose run --rm rsmanage rsmanage build overview`` (replace ``overview`` with the name of the course you added in the previous step). If you are building a PreTeXt book you will need to run ``docker compose run --rm rsmanage rsmanage build --ptx overview``
51
+
- Access your server at http://localhost
52
+
- Log in with username: ``testuser1``, password: ``xxx``
53
+
- Check ``init_runestone.log`` if you encounter any issues
46
54
47
-
#. 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``
55
+
Managing Your Server
56
+
--------------------
48
57
49
-
#. If you want to create a course for students to use, you can run the following command: ``docker compose run --rm rsmanage rsmanage addcourse`` This will create a course with the name you provide.
58
+
**Stopping and Starting:**
50
59
51
-
#. Additional commands are available (for example to add an instructor to a course). Run ``docker compose run --rm rsmanage rsmanage --help`` to see a list of available commands.
60
+
- Stop the server: ``docker compose stop``
61
+
- Start the server: ``docker compose start``
62
+
- Restart services: ``docker compose restart``
63
+
- Shut down and remove containers: ``docker compose down``
64
+
- Shut down and remove volumes (WARNING: deletes all data): ``docker compose down -v``
52
65
53
-
If you want to stop the server, you can run the following command: ``docker compose stop``
66
+
**Viewing Logs:**
67
+
68
+
To view logs from all services: ``docker compose logs -f``
69
+
70
+
**Common Management Tasks:**
71
+
72
+
- Add another book: ``docker compose run --rm rsmanage rsmanage addbookauthor``
73
+
- Build a book: ``docker compose run --rm rsmanage rsmanage build <bookname>``
74
+
- Build a PreTeXt book: ``docker compose run --rm rsmanage rsmanage build --ptx <bookname>``
75
+
- Create a course: ``docker compose run --rm rsmanage rsmanage addcourse``
76
+
- Add an instructor to a course: ``docker compose run --rm rsmanage rsmanage addinstructor``
77
+
78
+
**Troubleshooting:**
79
+
80
+
If you used the automated setup script (``init_runestone.sh``), check the ``init_runestone.log`` file in the rs directory for detailed information about the setup process. This log can help diagnose any issues that occurred during initialization.
81
+
82
+
For database issues, you can reset the database by running ``docker compose down -v`` to remove all volumes, then re-run the initialization steps (either manually or via ``./init_runestone.sh``).
83
+
84
+
Developer Setup (From Cloned Repository)
85
+
-----------------------------------------
86
+
87
+
If you're contributing to Runestone development or want the source code locally, clone the repository first:
The script will detect that ``docker-compose.yml`` and ``sample.env`` already exist and run in "traditional mode" without downloading files. All the same setup steps occur — you just have the source code available for development.
96
+
97
+
**Why clone the repository?**
98
+
99
+
- You want to modify Runestone server code
100
+
- You're contributing features or bug fixes
101
+
- You need to build Docker images locally instead of using pre-built ones
102
+
- You want to run tests or use additional development tools
103
+
104
+
For most users just running a Runestone server, cloning the repository is not necessary.
105
+
106
+
**For full development environment setup** (building from source, running tests, etc.), see the :doc:`developing` documentation.
107
+
108
+
How the Setup Script Works
109
+
---------------------------
110
+
111
+
The automated setup script performs several steps to get Runestone running. Understanding these steps can help you troubleshoot issues and better understand how Runestone works.
112
+
113
+
**Step 1: Platform Detection and Prerequisite Validation**
114
+
115
+
The script first detects your operating system (Linux, macOS, or Windows WSL2) and validates:
116
+
117
+
- Docker is installed and running
118
+
- Docker Compose version is 2.20.2 or later
119
+
- Git is installed (optional, but will warn if missing)
120
+
- On Linux (non-WSL), checks if you're in the docker group
121
+
122
+
**Step 2: Configuration File Setup**
123
+
124
+
The script determines if you're running in "standalone mode" or "traditional mode":
125
+
126
+
- **Standalone mode**: If ``docker-compose.yml`` and ``sample.env`` don't exist in the current directory, the script downloads them from the GitHub repository
127
+
- **Traditional mode**: If you've cloned the repository, it uses the existing files
128
+
129
+
This allows the script to work whether you've cloned the repo or are starting from scratch.
130
+
131
+
**Step 3: Environment Configuration (BOOK_PATH)**
132
+
133
+
The script creates a ``.env`` file and prompts you to configure ``BOOK_PATH`` — the directory where your Runestone books will be stored.
134
+
135
+
**What is BOOK_PATH?**
136
+
137
+
- A directory on your host machine (not inside Docker) where book source code lives
138
+
- This directory is mounted into Docker containers so they can access and build your books
139
+
- Example paths: ``~/runestone/books``, ``/home/username/books``, ``C:\Projects\books`` (Windows)
140
+
141
+
**Windows path handling:**
142
+
143
+
If you're on WSL2, you can provide paths in Windows format (``C:\Projects\books``) and the script automatically converts them to WSL format (``/mnt/c/Projects/books``).
144
+
145
+
**What happens to BOOK_PATH:**
146
+
147
+
- If the directory doesn't exist, the script offers to create it
148
+
- The path is saved to ``.env`` so Docker knows where to find your books
149
+
- You'll use this directory later when cloning book repositories
150
+
151
+
**Docker Desktop users:** Make sure this directory is shared with Docker. Go to Docker Desktop → Settings → Resources → File Sharing and add your ``BOOK_PATH`` directory to the list. This allows the Docker containers to access and build your books.
152
+
153
+
**Step 4: Docker Image Pulling**
154
+
155
+
The script runs ``docker compose pull`` to download pre-built Docker images from GitHub Container Registry (ghcr.io).
156
+
157
+
**What are these images?**
158
+
159
+
Runestone uses a microservices architecture with multiple servers:
- ``assignment_server`` - Handles assignments and grading
164
+
- ``rsmanage`` - Management tools for books and courses
165
+
- Several other services for authentication, logging, etc.
166
+
167
+
These images are pre-built, so you don't need the Runestone source code to run the server.
168
+
169
+
**Step 5: Database Initialization**
170
+
171
+
The script starts the PostgreSQL database container (``docker compose up -d db``) and initializes it with the Runestone schema (``rsmanage initdb``).
172
+
173
+
**What gets created:**
174
+
175
+
- Database tables for users, courses, books, assignments, responses, etc.
176
+
- Test user accounts including ``testuser1`` (password: ``xxx``)
177
+
- Base courses for popular Runestone books (``overview``, ``thinkcspy``, ``pythonds``, etc.) that can be used when registering books
178
+
179
+
This is the foundation that stores all your course data.
180
+
181
+
**Step 6: Start All Services**
182
+
183
+
The script starts all Runestone services (``docker compose up -d``), including:
184
+
185
+
- Web servers (book server, assignment server, etc.)
186
+
- Background workers for processing tasks
187
+
- An nginx reverse proxy to route requests
188
+
189
+
The services communicate with each other and the database to provide the full Runestone experience.
190
+
191
+
**Step 7: Book Setup (Optional)**
192
+
193
+
If you choose to add a book, the script:
194
+
195
+
#. **Clones the repository**: Downloads the book source code to your ``BOOK_PATH`` directory (e.g., ``git clone https://github.com/RunestoneInteractive/overview.git``)
196
+
197
+
#. **Registers the book**: Adds the book to the database using ``rsmanage addbookauthor``, creating a "base course" record associated with your user account
198
+
199
+
#. **Builds the book**: Runs ``rsmanage build`` to convert the book source (RST or PreTeXt) into interactive HTML with embedded questions, visualizations, and other Runestone features
200
+
201
+
**Base course vs. teaching course:**
202
+
203
+
- A "base course" is the master version of the book content
204
+
- When teaching a class, you create a separate course that references the base course
205
+
- This allows multiple instructors to teach from the same book with different settings
206
+
207
+
**Step 8: Course Creation (Optional)**
208
+
209
+
If you choose to create a course, the script runs ``rsmanage addcourse`` which:
210
+
211
+
- Creates a new course record in the database
212
+
- Links it to a base course (book)
213
+
- Sets up the course configuration (term dates, public/private status, etc.)
214
+
- Allows you to enroll students and manage assignments
215
+
216
+
Students will register for your course and use the book content within that course context.
217
+
218
+
**Setup Complete!**
219
+
220
+
After these steps, your Runestone server is fully operational and accessible at http://localhost.
54
221
55
-
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.
0 commit comments